{"openapi":"3.0.3","info":{"title":"Kyo Meta DEX Aggregator API","description":"# Kyo Meta DEX Aggregator\n\n![KYO.ag - DEX Aggregator for optimal token swap routing](/images/banner.png)\n\nMeta aggregator that finds the best swap route across multiple DEX aggregators through a **competition model**.\n\n## How It Works\n\n1. **Create a Competition** — Submit your swap parameters (chain, tokens, amount). The API creates a competition and returns a `competitionId` along with the list of available aggregators.\n2. **Fetch Quotes** — Query each aggregator using the `competitionId` to collect pricing quotes.\n3. **Compare Results** — Use the results endpoint to see all quotes ranked side by side.\n4. **Execute the Best Swap** — Call the swap endpoint with the winning aggregator to get transaction calldata.\n\n## Authentication\n\nAuthorization is optional for all endpoints:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\nCalls without an API key are supported. With an API key, partners can receive higher RPS limits (up to 10x) and revshare.\n\nVisit [portal.kyo.ag](https://portal.kyo.ag) to generate your API key.\n\n## Rate Limits\n\n- Without API key (Meta Aggregator APIs): 20 requests/minute\n- With API key: up to 10x of the above limits\n- Limits are subject to change; abusive traffic or persistently low swap-to-quote ratios may be throttled\n\n## Competition Lifecycle\n\nCompetitions have a short TTL. Once expired, quote and swap requests will return `410 Gone`.\n\n\n## Chain Discovery\n\nUse `GET /chains` to fetch the latest supported chain IDs for both KYO aggregator and Meta Aggregator flows.\n- `meta.chains`: chain IDs available for `POST /competitions`\n- `kyoAg.chains`: chain IDs currently live on KYO `/v1/*` endpoints\n","license":{"name":""},"version":"0.1.0"},"servers":[{"url":"https://api.kyo.ag","description":"Production API"}],"paths":{"/competitions":{"post":{"tags":["Competitions"],"operationId":"create_competition","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompetitionRequest"},"example":{"chainId":999,"tokenIn":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","tokenOut":"0xb88339cb7199b77e23db6e890353e22632ba630f","amountIn":"1000000000000000000","userAddress":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","slippage":0.01},"examples":{"hypeToUsdcSell":{"summary":"1 HYPE to USDC on HyperEVM (chainId 999)","value":{"chainId":999,"tokenIn":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","tokenOut":"0xb88339cb7199b77e23db6e890353e22632ba630f","amountIn":"1000000000000000000","userAddress":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","slippage":0.01}}}}},"required":true},"responses":{"200":{"description":"Competition created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompetitionResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Unauthorized"}}}},"/competitions/{id}/results":{"get":{"tags":["Competitions"],"operationId":"get_results","parameters":[{"name":"id","in":"path","description":"Competition ID","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Competition results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitionResultsResponse"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Competition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"description":"Competition expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/health":{"get":{"tags":["Health"],"operationId":"health","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{}}}}}}},"/quotes":{"post":{"tags":["Quotes"],"summary":"POST /quotes?aggregator=X&competitionId=Y","description":"Returns pricing info only (no calldata).","operationId":"get_quote","parameters":[{"name":"aggregator","in":"query","required":true,"schema":{"type":"string"}},{"name":"competitionId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Quote retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Competition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"description":"Competition expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/swap":{"post":{"tags":["Swap"],"summary":"POST /swap?aggregator=X&competitionId=Y","description":"Returns calldata for tx execution.","operationId":"get_swap","parameters":[{"name":"aggregator","in":"query","required":true,"schema":{"type":"string"}},{"name":"competitionId","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Swap calldata retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SwapResponse"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"401":{"description":"Unauthorized"},"404":{"description":"Competition not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}},"410":{"description":"Competition expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorBody"}}}}}}},"/chains":{"get":{"tags":["Chains"],"summary":"List supported chains","description":"Returns chain IDs available on KYO.ag. Use `meta.chains` when selecting `chainId` for `POST /competitions`.","operationId":"chains","responses":{"200":{"description":"Supported chains returned successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChainsResponse"}}}}}}}},"components":{"schemas":{"CompetitionResultsResponse":{"type":"object","description":"Response for competition results.","required":["competitionId","chainId","tokenIn","tokenOut","amountIn","quotes"],"properties":{"amountIn":{"type":"string"},"chainId":{"type":"integer","format":"int64","minimum":0},"competitionId":{"type":"string"},"quotes":{"type":"array","items":{"$ref":"#/components/schemas/NormalizedQuote"}},"tokenIn":{"type":"string"},"tokenOut":{"type":"string"}}},"CreateCompetitionRequest":{"type":"object","description":"Request to create a new competition.","required":["chainId","tokenIn","tokenOut","amountIn","userAddress","slippage"],"properties":{"amountIn":{"type":"string"},"chainId":{"type":"integer","format":"int64","minimum":0,"description":"Chain ID for the competition. Fetch latest values from `GET /chains` (`meta.chains`)."},"slippage":{"type":"number","format":"double"},"tokenIn":{"type":"string"},"tokenInDecimals":{"type":"integer","format":"int32","description":"Decimals of token_in (needed for LiquidSwap). Defaults to 18.","nullable":true,"minimum":0},"tokenOut":{"type":"string"},"userAddress":{"type":"string"}},"example":{"chainId":999,"tokenIn":"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee","tokenOut":"0xb88339cb7199b77e23db6e890353e22632ba630f","amountIn":"1000000000000000000","userAddress":"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045","slippage":0.01}},"CreateCompetitionResponse":{"type":"object","description":"Response after creating a competition.","required":["competitionId","availableAggregators","chainId","expiresAt"],"properties":{"availableAggregators":{"type":"array","items":{"type":"string"}},"chainId":{"type":"integer","format":"int64","minimum":0},"competitionId":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"ErrorBody":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}},"NormalizedQuote":{"type":"object","description":"Pricing-only quote (no calldata).","required":["aggregator","tokenIn","tokenOut","amountIn","amountOut"],"properties":{"aggregator":{"type":"string"},"amountIn":{"type":"string"},"amountOut":{"type":"string"},"gasEstimate":{"type":"string","nullable":true},"tokenIn":{"type":"string"},"tokenOut":{"type":"string"}}},"NormalizedSwap":{"type":"object","description":"Swap response with calldata for tx execution.","required":["aggregator","tokenIn","tokenOut","amountIn","amountOut","to","data","value","allowanceTarget"],"properties":{"aggregator":{"type":"string"},"allowanceTarget":{"type":"string","description":"Contract that needs token approval (may differ from `to`)."},"amountIn":{"type":"string"},"amountOut":{"type":"string"},"data":{"type":"string","description":"Calldata for the swap tx."},"gasEstimate":{"type":"string","nullable":true},"to":{"type":"string","description":"Contract to send the swap tx to."},"tokenIn":{"type":"string"},"tokenOut":{"type":"string"},"value":{"type":"string","description":"Native value to send with tx (for native token sells)."}}},"QuoteQuery":{"type":"object","description":"Query params for /quotes and /swap.","required":["aggregator","competitionId"],"properties":{"aggregator":{"type":"string"},"competitionId":{"type":"string"}}},"QuoteResponse":{"allOf":[{"type":"object","description":"Pricing-only quote (no calldata).","required":["aggregator","tokenIn","tokenOut","amountIn","amountOut"],"properties":{"aggregator":{"type":"string"},"amountIn":{"type":"string"},"amountOut":{"type":"string"},"gasEstimate":{"type":"string","nullable":true},"tokenIn":{"type":"string"},"tokenOut":{"type":"string"}}},{"type":"object","required":["competitionId"],"properties":{"competitionId":{"type":"string"}}}],"description":"Response for a single quote request."},"SwapResponse":{"allOf":[{"type":"object","description":"Swap response with calldata for tx execution.","required":["aggregator","tokenIn","tokenOut","amountIn","amountOut","to","data","value","allowanceTarget"],"properties":{"aggregator":{"type":"string"},"allowanceTarget":{"type":"string","description":"Contract that needs token approval (may differ from `to`)."},"amountIn":{"type":"string"},"amountOut":{"type":"string"},"data":{"type":"string","description":"Calldata for the swap tx."},"gasEstimate":{"type":"string","nullable":true},"to":{"type":"string","description":"Contract to send the swap tx to."},"tokenIn":{"type":"string"},"tokenOut":{"type":"string"},"value":{"type":"string","description":"Native value to send with tx (for native token sells)."}}},{"type":"object","required":["competitionId"],"properties":{"competitionId":{"type":"string"}}}],"description":"Response for a swap request."},"ChainInfo":{"type":"object","required":["chainId","name"],"properties":{"chainId":{"type":"integer","format":"int64","minimum":0,"example":999,"description":"EVM chain ID"},"name":{"type":"string","example":"HyperEVM","description":"Human-readable chain name"}}},"ChainsResponse":{"type":"object","required":["meta","kyoAg"],"properties":{"meta":{"type":"object","required":["chains"],"properties":{"chains":{"type":"array","description":"Chains available for Meta Aggregator competitions","items":{"$ref":"#/components/schemas/ChainInfo"}}}},"kyoAg":{"type":"object","required":["chains"],"properties":{"chains":{"type":"array","description":"Chains currently supported by KYO Aggregator `/v1/*` endpoints","items":{"$ref":"#/components/schemas/ChainInfo"}}}}},"example":{"meta":{"chains":[{"chainId":1,"name":"Ethereum"},{"chainId":999,"name":"HyperEVM"},{"chainId":1868,"name":"Soneium"}]},"kyoAg":{"chains":[{"chainId":999,"name":"HyperEVM"},{"chainId":1868,"name":"Soneium"}]}}}},"securitySchemes":{"bearer_auth":{"type":"http","scheme":"bearer"}}},"tags":[{"name":"Health","description":"Health check"},{"name":"Competitions","description":"Competition lifecycle"},{"name":"Quotes","description":"Price quotes"},{"name":"Swap","description":"Swap calldata"},{"name":"Chains","description":"Discover supported chains via `GET /chains`."}]}