KYO.ag API Reference
KYO.ag provides aggregator, meta aggregator, and cross-chain APIs. Use it to swap tokens, zap into Uniswap V3 LP positions, rebalance positions, bridge across chains, and discover supported chains dynamically via /chains.
Key Features
- Mathematically Optimal — Provably best routes through mathematical optimization
- Rust Performance — High-speed execution powered by Rust engine
- Multi-Chain — Unified API across multiple EVM chains
- Split Routes — Automatically splits large orders across pools for better pricing
- Single-Sided LP — Zap into Uniswap V3 positions with any token
- Position Rebalancing — Adjust LP tick ranges without manual withdrawals
Supported Chains
| Chain | Chain ID | Base URL |
|---|
| HyperEVM | 999 | https://api.kyo.ag/999/v1/ |
| Soneium | 1868 | https://api.kyo.ag/1868/v1/ |
Need the latest chain IDs? Call GET https://api.kyo.ag/chains. Use kyoAg.chains for Aggregator endpoints (/v1/*) and meta.chains for Meta Aggregator competitions.
Authentication
Authorization is optional for all endpoints. Partners with an API key receive higher RPS limits (up to 10x) and revshare. Visit portal.kyo.ag to generate your API key.
Authorization: Bearer YOUR_API_KEY
Rate Limits
- Without API key (Aggregator APIs): 60 requests/minute
- Without API key (Meta Aggregator APIs): 20 requests/minute
- With API key: Up to 10x of the above limits
POST /v1/quote — Get a Swap Quote
Returns the optimal swap route and expected amounts without building transaction data. Supports sell mode (specify amountIn) and buy mode (specify amountOut). Live responses also include priceImpactPct when available.
| Field | Type | Required | Description |
|---|
| tokenIn | string | Yes | Input token address |
| tokenOut | string | Yes | Output token address |
| amountIn | string | Conditional | Input amount in wei (sell mode) |
| amountOut | string | Conditional | Output amount in wei (buy mode) |
| slippage | number | No | Slippage tolerance (default 0.005) |
| partnerFeeBps | integer | No | Partner fee in basis points (max 100) |
curl -X POST https://api.kyo.ag/999/v1/quote \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"tokenIn":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","tokenOut":"0xb88339cb7199b77e23db6e890353e22632ba630f","amountIn":"1000000000000000000"}'
POST /v1/swap — Execute Token Swap
Get optimal swap route with ready-to-sign transaction data. Includes all quote fields plus userAddress (required) and returns calldata, router address, and transaction array. The nested quote object also includes priceImpactPct when available.
| Field | Type | Required | Description |
|---|
| userAddress | string | Yes | Wallet address executing the swap |
| tokenIn | string | Yes | Input token address |
| tokenOut | string | Yes | Output token address |
| amountIn | string | Yes | Input amount in wei |
| slippage | number | No | Slippage tolerance |
Transaction execution: For native token input, send with value = amountIn. For ERC20, execute approve transaction first, then the swap transaction.
POST /v1/zap — Single-Sided LP Provision
Provide liquidity to a Uniswap V3 position using any single token. KYO.ag automatically swaps to the optimal ratio and mints or increases a position in one transaction.
| Field | Type | Required | Description |
|---|
| userAddress | string | Yes | Wallet address |
| tokenIn | string | Yes | Input token address |
| amountIn | string | Yes | Input amount in wei |
| poolAddress | string | Yes | Target Uniswap V3 pool |
| positionManager | string | Yes | NFT position manager contract |
| tickLower | integer | Yes | Lower tick of position range |
| tickUpper | integer | Yes | Upper tick of position range |
| positionId | string | No | Existing position to increase |
POST /v1/rebalance — Rebalance LP Position
Rebalance a Uniswap V3 LP position to a new tick range. The old position is withdrawn and a new one is minted with the specified range, all in a single transaction.
| Field | Type | Required | Description |
|---|
| userAddress | string | Yes | Position owner wallet |
| positionManager | string | Yes | NFT position manager contract |
| positionId | string | Yes | Position NFT ID |
| tickLower | integer | No | New lower tick (auto-centers if omitted) |
| tickUpper | integer | No | New upper tick (auto-centers if omitted) |
GET /v1/sources — List DEX Sources
List available DEX sources for filtering. No authentication required. Returns chainId and sources array with source IDs and names. Use these IDs with includedSources or excludedSources on other endpoints.
curl https://api.kyo.ag/999/v1/sources
Cross-Chain API
The Cross-Chain API is served from https://cross-chain-api.kyo.ag. It provides /v1/chains, /v1/currencies, /v1/quote, and /v1/transactions/{sourceTxHash} for quote discovery, execution, and status polling.
curl https://cross-chain-api.kyo.ag/v1/chains
GET /chains — List Supported Chains
Returns supported chain IDs for both products. Use kyoAg.chains for Aggregator APIs (/v1/*) and meta.chains for Meta Aggregator competition requests.
curl https://api.kyo.ag/chains
Error Handling
| Error Code | Description |
|---|
| INVALID_TOKEN | Token address is invalid or not supported |
| INVALID_AMOUNT | Amount is zero, negative, or malformed |
| NO_ROUTE_FOUND | No liquidity path exists between tokens |
| INSUFFICIENT_LIQUIDITY | Route exists but liquidity is too low |
| INVALID_PARAMETERS | Request parameters are invalid |
| INTERNAL_ERROR | Server-side error |
Frequently Asked Questions
How do I swap tokens using KYO.ag API?
Send a POST request to https://api.kyo.ag/{chainId}/v1/swap with your tokenIn, tokenOut, amountIn, and userAddress in the JSON body. Include your API key as a Bearer token in the Authorization header. The API returns optimally-routed transaction calldata ready to sign and broadcast. Use /v1/quote first if you only need pricing without transaction data. Get your API key instantly at portal.kyo.ag.
What chains does KYO.ag support?
Use GET https://api.kyo.ag/chains to discover the latest chain IDs. The response includes kyoAg.chains for Aggregator endpoints (/v1/*) and meta.chains for Meta Aggregator competitions. Aggregator base URL pattern: https://api.kyo.ag/{chainId}/v1/{endpoint}.
How do I provide single-sided liquidity with KYO.ag?
Use the POST /v1/zap endpoint to provide single-sided liquidity into Uniswap V3 positions. Supply any single token and specify the target pool address, position manager contract, and tick range (tickLower, tickUpper). KYO.ag automatically swaps the optimal ratio and mints or increases a V3 LP position in one transaction.
What is the KYO.ag Meta Aggregator?
The Meta Aggregator compares quotes from multiple DEX aggregators through a competition model. Create a competition with your swap parameters, fetch quotes from each available aggregator in parallel, compare results ranked by output amount, then execute the best swap. This ensures you always get the best rate across all aggregator sources.
Does KYO.ag have a cross-chain API?
Yes. See Cross-Chain API. The API is served from https://cross-chain-api.kyo.ag and supports chain discovery, currency discovery, executable quote creation, and transaction status polling.
Machine-Readable Documentation
