How It Works
- Create a Competition — Submit your swap parameters (chain, tokens, amount, slippage). The API creates a competition and returns a
competitionId along with available aggregators.
- Fetch Quotes — Query each aggregator using the
competitionId to collect pricing quotes. Run these in parallel for speed.
- Compare Results — Use the results endpoint to see all quotes ranked by output amount.
- Execute the Best Swap — Call the swap endpoint with the winning aggregator to get transaction calldata.
Competitions have a short TTL. Once expired, quote and swap requests return 410 Gone.
Base URL & Authentication
Base URL: https://api.kyo.ag
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
POST /competitions — Create a Competition
Submit swap parameters and receive a competitionId with the list of available aggregators to query.
| Field | Type | Required | Description |
|---|
| chainId | integer | Yes | Chain ID from GET /chains (meta.chains) |
| tokenIn | string | Yes | Input token address |
| tokenOut | string | Yes | Output token address |
| amountIn | string | Yes | Input amount in wei |
| userAddress | string | Yes | User wallet address |
| slippage | number | Yes | Slippage tolerance (0.01 = 1%) |
Response returns competitionId, availableAggregators array, chainId, and expiresAt timestamp.
curl -X POST https://api.kyo.ag/competitions \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"chainId":999,"tokenIn":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","tokenOut":"0xb88339cb7199b77e23db6e890353e22632ba630f","amountIn":"1000000000000000000","userAddress":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","slippage":0.01}'
POST /quotes — Fetch Quote from Aggregator
Fetch a pricing quote from a specific aggregator. No request body needed — uses query parameters only.
Query parameters: aggregator (required) and competitionId (required).
Returns: aggregator name, tokenIn, tokenOut, amountIn, amountOut, gasEstimate, and competitionId.
curl -X POST "https://api.kyo.ag/quotes?aggregator=kyo&competitionId=abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
GET /chains — Discover Chain IDs
Fetch the latest supported chain IDs before creating competitions. Use meta.chains from the response as valid values for POST /competitions chainId.
curl https://api.kyo.ag/chains
GET /competitions/{id}/results — Compare Results
Get all quotes for a competition, ranked by output amount (best quote first). Returns competitionId, chainId, tokenIn, tokenOut, amountIn, and a quotes array sorted by amountOut descending.
curl https://api.kyo.ag/competitions/abc123/results \
-H "Authorization: Bearer YOUR_API_KEY"
POST /swap — Execute Best Swap
Get transaction calldata for the chosen aggregator. No request body — uses query parameters aggregator and competitionId.
Returns: calldata (data), contract address (to), native value, allowanceTarget for token approval. For native token input, send value with the transaction. For ERC20, approve allowanceTarget first.
curl -X POST "https://api.kyo.ag/swap?aggregator=kyo&competitionId=abc123" \
-H "Authorization: Bearer YOUR_API_KEY"
Error Handling
| HTTP Status | Description | Action |
|---|
| 400 | Bad request — invalid parameters | Check required fields and types |
| 401 | Unauthorized — missing or invalid API key | Verify Bearer token |
| 404 | Competition not found | Create a new competition |
| 410 | Competition expired | Create a new competition and retry |
Machine-Readable Documentation
