{ "openapi": "3.0.3", "info": { "title": "KYO.ag API", "description": "# KYO.ag\n\n![KYO.ag - DEX Aggregator for optimal token swap routing](/images/banner.png)\n\nKYO.ag is a multi-chain DEX aggregator. Built in Rust for speed, with mathematically optimal routing.\n\n## Base URL\n\nAggregator endpoints follow this URL pattern:\n\n```\nhttps://api.kyo.ag/{chainId}/v1/{endpoint}\n```\n\nFor global chain discovery, use:\n\n```\nhttps://api.kyo.ag/chains\n```\n\n### Supported Chains\n\n| Chain | Chain ID | Example Base URL |\n|-------|----------|------------------|\n| HyperEVM | 999 | `https://api.kyo.ag/999/v1/` |\n| Soneium | 1868 | `https://api.kyo.ag/1868/v1/` |\n\n> More chains are being added rapidly. Stay tuned for updates.\n\n## Key Features\n\n| Feature | Description |\n|---------|-------------|\n| **Mathematically Optimal** | Provably best routes through mathematical optimization |\n| **Rust Performance** | High-speed execution powered by Rust engine |\n| **Multi-Chain** | Unified API across multiple EVM chains |\n| **Split Routes** | Automatically splits large orders across pools |\n| **Single-Sided LP** | Zap into Uniswap V3 positions with any token |\n| **Position Rebalancing** | Adjust LP tick ranges without manual withdrawals |\n\n## Quick Start\n\n### 1. Get a Quote\n\n```bash\ncurl -X POST https://api.kyo.ag/999/v1/quote \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"tokenIn\": \"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n \"tokenOut\": \"0xb88339cb7199b77e23db6e890353e22632ba630f\",\n \"amountIn\": \"1000000000000000000\"\n }'\n```\n\n### 2. Execute Swap\n\n```bash\ncurl -X POST https://api.kyo.ag/999/v1/swap \\\n -H \"Authorization: Bearer YOUR_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"tokenIn\": \"0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\n \"tokenOut\": \"0xb88339cb7199b77e23db6e890353e22632ba630f\",\n \"amountIn\": \"1000000000000000000\",\n \"userAddress\": \"0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045\"\n }'\n```\n\n## Authentication\n\nAuthorization is optional for all endpoints:\n\n```\nAuthorization: Bearer YOUR_API_KEY\n```\n\n> [!tip]\n> Calls without an API key are supported. Partners with an API key can receive higher RPS limits (up to 10x) and revshare.\n> Visit [portal.kyo.ag](https://portal.kyo.ag) to generate your API key.\n\n## Rate Limits\n\n| Tier | Limit |\n|------|-------|\n| Without API key (Aggregator APIs) | 60 requests/minute |\n| Without API key (Meta Aggregator APIs) | 20 requests/minute |\n| With API key | Up to 10x of the above limits |\n\n> [!warning]\n> Limits are subject to change. Abusive traffic or persistently low swap-to-quote ratios may be throttled.\n\n## Native Token Address\n\nFor native tokens (ETH, etc.), use:\n```\n0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\n```\n\n## Error Handling\n\nAll errors return a JSON object with `error` code and `message`:\n\n```json\n{\n \"error\": \"NO_ROUTE_FOUND\",\n \"message\": \"No route found between the specified tokens\"\n}\n```\n\n| Error Code | Description |\n|------------|-------------|\n| INVALID_TOKEN | Token address is invalid or not supported |\n| INVALID_AMOUNT | Amount is zero, negative, or malformed |\n| NO_ROUTE_FOUND | No liquidity path exists between tokens |\n| INSUFFICIENT_LIQUIDITY | Route exists but liquidity is too low |\n| INVALID_PARAMETERS | Request parameters are invalid |\n| INTERNAL_ERROR | Server-side error |\n\n\n## Chain Discovery\n\nUse `GET https://api.kyo.ag/chains` to fetch the latest supported chain IDs.\n- `kyoAg.chains`: chains currently live for `/v1/*` endpoints\n- `meta.chains`: chains available for Meta Aggregator competitions\n", "license": { "name": "MIT" }, "version": "1.0.0" }, "servers": [ { "url": "https://api.kyo.ag/{chainId}", "description": "Production Aggregator API (/v1/*)", "variables": { "chainId": { "default": "999", "description": "Chain ID", "enum": [ "999", "1868" ] } } } ], "paths": { "/v1/quote": { "post": { "tags": [ "Swap" ], "summary": "Get a swap quote", "description": "Returns the optimal swap route and expected amounts without building transaction data.\nUse this endpoint to preview swap results before executing.\n\n## Modes\n- **Sell mode**: Specify `amountIn` to sell a fixed amount of input token\n- **Buy mode**: Specify `amountOut` to buy a fixed amount of output token\n\n## Partner Fee\nPartner fees are collected from the OUTPUT token. For sell mode, the fee is deducted\nfrom the output amount. For buy mode, the router calculates the extra input needed.", "operationId": "quote_handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteRequest" }, "examples": { "sellMode": { "summary": "Sell 1 HYPE for USDC on HyperEVM", "value": { "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f", "amountIn": "1000000000000000000", "slippage": 0.01 } }, "buyMode": { "summary": "Buy 1 USDC with HYPE on HyperEVM", "value": { "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f", "amountOut": "1000000", "slippage": 0.01 } } } } }, "required": true }, "responses": { "200": { "description": "Swap quote calculated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuoteResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No route found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/rebalance": { "post": { "tags": [ "Rebalance" ], "summary": "Rebalance a Uniswap V3 LP position", "description": "Withdraws liquidity from an existing position and mints a new position\nwith a different tick range. Automatically swaps tokens to optimal ratio.\n\n## Partner Fee\nPartner fees are applied to the LP fee during mint operations.\nThe partner portion is tracked via events for offchain settlement.", "operationId": "rebalance_handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RebalanceRequest" }, "examples": { "autoCenter": { "summary": "Auto-center existing position (recommended default)", "value": { "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "positionManager": "0x1234567890123456789012345678901234567890", "positionId": "12345", "slippage": 0.01 } }, "customRange": { "summary": "Rebalance with explicit tick range", "value": { "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "positionManager": "0x1234567890123456789012345678901234567890", "positionId": "12345", "tickLower": -60000, "tickUpper": 60000, "slippage": 0.01 } } } } }, "required": true }, "responses": { "200": { "description": "Rebalance transaction built successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RebalanceResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Position or pool not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/sources": { "get": { "tags": [ "Sources" ], "summary": "List available DEX sources", "description": "Returns all DEX sources available for filtering on the current chain.\nUse the source IDs with `includedSources` or `excludedSources` in quote/swap requests.", "operationId": "sources_handler", "responses": { "200": { "description": "List of available DEX sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SourcesResponse" } } } } } } }, "/v1/swap": { "post": { "tags": [ "Swap" ], "summary": "Execute a token swap", "description": "Returns the optimal swap route, quote information, and ready-to-sign transaction data.\nThe response includes both the quote details and transaction calldata that can be\nsubmitted directly to the blockchain. The nested `quote` object reuses `QuoteResponse`,\nincluding `priceImpactPct` when available.\n\n## Modes\n- **Sell mode**: Specify `amountIn` to sell a fixed amount of input token\n- **Buy mode**: Specify `amountOut` to buy a fixed amount of output token\n\n## Partner Fee\nPartner fees are collected from the OUTPUT token. For sell mode, the fee is deducted\nfrom the output amount. For buy mode, the router calculates the extra input needed.\n\n## Transaction Execution\nFor native token input (ETH/MATIC/etc), send the transaction value equal to `amountIn`\n(sell mode) or `maxInputAmount` (buy mode). For ERC20 input, approve the router first.", "operationId": "swap_handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapRequest" }, "examples": { "sellMode": { "summary": "Sell 1 HYPE for USDC on HyperEVM", "value": { "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f", "amountIn": "1000000000000000000", "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "slippage": 0.01 } }, "buyMode": { "summary": "Buy 1 USDC with HYPE on HyperEVM", "value": { "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f", "amountOut": "1000000", "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "slippage": 0.01 } } } } }, "required": true }, "responses": { "200": { "description": "Swap transaction built successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SwapResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No route found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/zap": { "post": { "tags": [ "Zap" ], "summary": "Zap into a Uniswap V3 LP position", "description": "Performs a single-sided liquidity provision by swapping input token to the optimal\nratio for the specified tick range and minting/increasing an LP position.\n\n## Partner Fee\nPartner fees are applied to the LP fee during mint/increase operations.\nThe partner portion is tracked via events for offchain settlement.\n\n## Transaction Execution\nFor native token input (ETH/MATIC/etc), send the transaction value equal to `amountIn`.\nFor ERC20 input, approve the router first.", "operationId": "zap_handler", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ZapRequest" }, "examples": { "mintPosition": { "summary": "UltraSolid HYPE-USDC pool (mint new position)", "value": { "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "amountIn": "1000000000000000000", "poolAddress": "0x3e69297ae794011970256623b4ab68324983b9ed", "positionManager": "0xE7ffA0ee20Deb1613489556062Fa8cec690C3c02", "tickLower": -887220, "tickUpper": 887220, "slippage": 0.01 } }, "increasePosition": { "summary": "UltraSolid HYPE-USDC pool (increase existing position)", "value": { "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "amountIn": "1000000000000000000", "poolAddress": "0x3e69297ae794011970256623b4ab68324983b9ed", "positionManager": "0xE7ffA0ee20Deb1613489556062Fa8cec690C3c02", "tickLower": -887220, "tickUpper": 887220, "slippage": 0.01, "positionId": "12345" } } }, "example": { "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "amountIn": "1000000000000000000", "poolAddress": "0x3e69297ae794011970256623b4ab68324983b9ed", "positionManager": "0xE7ffA0ee20Deb1613489556062Fa8cec690C3c02", "tickLower": -887220, "tickUpper": 887220, "slippage": 0.01 } } }, "required": true }, "responses": { "200": { "description": "Zap transaction built successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ZapResponse" } } } }, "400": { "description": "Invalid request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "No route found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/chains": { "get": { "tags": [ "Chains" ], "summary": "List supported chains", "description": "Returns chain IDs available on KYO.ag. `kyoAg.chains` is the current support matrix for `/v1/*` aggregator endpoints, and `meta.chains` is the chain universe available for Meta Aggregator competitions.", "operationId": "chains_handler", "responses": { "200": { "description": "Supported chains returned successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChainsResponse" } } } } }, "servers": [ { "url": "https://api.kyo.ag", "description": "Global API endpoints" } ] } } }, "components": { "schemas": { "ErrorCode": { "type": "string", "enum": [ "INVALID_TOKEN", "INVALID_AMOUNT", "NO_ROUTE_FOUND", "INSUFFICIENT_LIQUIDITY", "INVALID_PARAMETERS", "INTERNAL_ERROR" ] }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "$ref": "#/components/schemas/ErrorCode" }, "message": { "type": "string", "description": "Human-readable error message", "example": "No route found between the specified tokens" } } }, "PartnerFeeInfo": { "type": "object", "required": [ "feeBps", "partnerId", "feeToken", "feeAmount" ], "properties": { "feeAmount": { "type": "string", "description": "Fee amount in fee_token's wei", "example": "3500000" }, "feeBps": { "type": "integer", "format": "int32", "description": "Fee in basis points", "example": 10, "minimum": 0 }, "feeToken": { "type": "string", "description": "Token in which fee is collected", "example": "0xb88339cb7199b77e23db6e890353e22632ba630f" }, "partnerId": { "type": "integer", "format": "int32", "description": "Partner ID for claim tracking", "example": 1, "minimum": 0 } } }, "QuoteRequest": { "type": "object", "required": [ "tokenIn", "tokenOut" ], "oneOf": [ { "required": [ "amountIn" ] }, { "required": [ "amountOut" ] } ], "example": { "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f", "amountIn": "1000000000000000000", "slippage": 0.01 }, "properties": { "amountIn": { "type": "string", "description": "Input amount in wei (required for sell mode)", "example": "1000000000000000000", "nullable": true }, "amountOut": { "type": "string", "description": "Output amount in wei (required for buy mode)", "example": "1000000", "nullable": true }, "excludedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to exclude (see /v1/sources endpoint)", "example": [ 3 ], "nullable": true }, "includedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to include exclusively (see /v1/sources endpoint)", "example": [ 1, 2 ], "nullable": true }, "partnerFeeBps": { "type": "integer", "format": "int32", "description": "Partner fee in basis points (100 = 1%, max 100)", "example": 10, "minimum": 0 }, "slippage": { "type": "number", "format": "double", "description": "Slippage tolerance as decimal (0.01 = 1%). Default: 0.005", "example": 0.01 }, "tokenIn": { "type": "string", "description": "Input token address (use 0xeeee...eeee for native token)", "example": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, "tokenOut": { "type": "string", "description": "Output token address (use 0xeeee...eeee for native token)", "example": "0xb88339cb7199b77e23db6e890353e22632ba630f" } } }, "QuoteResponse": { "type": "object", "required": [ "tokenIn", "tokenOut", "amountIn", "amountOut", "slippage", "tokens", "swaps", "sourcesAndSinks", "blockNumber" ], "properties": { "amountIn": { "type": "string", "description": "Input amount in wei", "example": "1000000000000000000" }, "amountOut": { "type": "string", "description": "Expected output amount in wei (before slippage)", "example": "3500000000" }, "blockNumber": { "type": "integer", "format": "int64", "description": "Block number at which quote was calculated", "example": 12345678, "minimum": 0 }, "maxInputAmount": { "type": "string", "description": "Maximum input amount after slippage (buy mode only)", "example": "1010000000000000000", "nullable": true }, "minOutputAmount": { "type": "string", "description": "Minimum output amount after slippage (sell mode only)", "example": "3465000000", "nullable": true }, "partnerFee": { "allOf": [ { "$ref": "#/components/schemas/PartnerFeeInfo" } ], "nullable": true }, "partnerId": { "type": "integer", "format": "int32", "description": "Partner ID (from API key)", "example": 1, "nullable": true, "minimum": 0 }, "priceImpactPct": { "type": "number", "format": "double", "description": "Estimated price impact percentage. May be null when unavailable.", "example": -0.02327814805609396, "nullable": true }, "slippage": { "type": "number", "format": "double", "description": "Slippage tolerance applied", "example": 0.01 }, "sourcesAndSinks": { "type": "array", "items": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string" } ] } }, "description": "Token amounts by address (negative = spend, positive = receive)" }, "swaps": { "type": "array", "items": { "$ref": "#/components/schemas/SwapStep" }, "description": "Detailed swap steps" }, "tokenIn": { "type": "string", "description": "Input token address", "example": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, "tokenOut": { "type": "string", "description": "Output token address", "example": "0xb88339cb7199b77e23db6e890353e22632ba630f" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/TokenInfo" }, "description": "All tokens involved in the route" } } }, "RebalanceQuoteResponse": { "type": "object", "required": [ "positionId", "poolAddress", "slippage", "tickLower", "tickUpper", "logPriceImpact", "tokens", "swaps", "sourcesAndSinks", "variableMin", "liquidityAmount", "blockNumber" ], "properties": { "blockNumber": { "type": "integer", "format": "int64", "description": "Block number at which quote was calculated", "example": 12345678, "minimum": 0 }, "liquidityAmount": { "type": "string", "description": "Expected liquidity amount to be minted in new position", "example": "1000000000000000000" }, "logPriceImpact": { "type": "number", "format": "double", "description": "Price impact (log scale)", "example": -0.001 }, "partnerFeeBps": { "type": "integer", "format": "int32", "description": "Partner fee in basis points (100 = 1%)", "example": 10, "nullable": true, "minimum": 0 }, "partnerId": { "type": "integer", "format": "int32", "description": "Partner ID (from API key)", "example": 1, "nullable": true, "minimum": 0 }, "poolAddress": { "type": "string", "description": "Target pool address", "example": "0x1234567890123456789012345678901234567890" }, "positionId": { "type": "string", "description": "Original position ID being rebalanced", "example": "12345" }, "slippage": { "type": "number", "format": "double", "description": "Applied slippage tolerance", "example": 0.01 }, "sourcesAndSinks": { "type": "array", "items": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string" } ] } }, "description": "Token amounts by address (negative = spend, positive = receive)" }, "swaps": { "type": "array", "items": { "$ref": "#/components/schemas/SwapStep" }, "description": "Detailed swap steps" }, "tickLower": { "type": "integer", "format": "int32", "description": "New lower tick for the position", "example": -887220 }, "tickUpper": { "type": "integer", "format": "int32", "description": "New upper tick for the position", "example": 887220 }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/TokenInfo" }, "description": "All tokens involved in the operation" }, "variableMin": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string" } ] }, "description": "The variable (output) token and minimum amount after slippage" } } }, "SourceInfo": { "type": "object", "required": [ "id", "name", "description" ], "properties": { "description": { "type": "string", "description": "Human-readable description (e.g., \"Kyo V3\")", "example": "Kyo V3" }, "id": { "type": "integer", "format": "int32", "description": "Unique source ID for filtering", "example": 1, "minimum": 0 }, "name": { "type": "string", "description": "Short name for the source (e.g., \"kyo_v3\")", "example": "kyo_v3" } } }, "SourcesResponse": { "type": "object", "required": [ "chainId", "sources" ], "properties": { "chainId": { "type": "integer", "format": "int64", "description": "Current chain ID", "example": 999, "minimum": 0 }, "sources": { "type": "array", "items": { "$ref": "#/components/schemas/SourceInfo" }, "description": "List of available DEX sources for this chain" } } }, "SwapRequest": { "type": "object", "required": [ "tokenIn", "tokenOut", "userAddress" ], "oneOf": [ { "required": [ "amountIn" ] }, { "required": [ "amountOut" ] } ], "example": { "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f", "amountIn": "1000000000000000000", "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "slippage": 0.01 }, "properties": { "amountIn": { "type": "string", "description": "Input amount in wei (required for sell mode)", "example": "1000000000000000000", "nullable": true }, "amountOut": { "type": "string", "description": "Output amount in wei (required for buy mode)", "example": "1000000", "nullable": true }, "approveMax": { "type": "boolean", "description": "If true, approve unlimited amount", "example": false }, "excludedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to exclude (see /v1/sources endpoint)", "example": [ 3 ], "nullable": true }, "includedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to include exclusively (see /v1/sources endpoint)", "example": [ 1, 2 ], "nullable": true }, "partnerFeeBps": { "type": "integer", "format": "int32", "description": "Partner fee in basis points (100 = 1%, max 100)", "example": 10, "minimum": 0 }, "slippage": { "type": "number", "format": "double", "description": "Slippage tolerance as decimal (0.01 = 1%)", "example": 0.01 }, "tokenIn": { "type": "string", "description": "Input token address (use 0xeeee...eeee for native token)", "example": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, "tokenOut": { "type": "string", "description": "Output token address (use 0xeeee...eeee for native token)", "example": "0xb88339cb7199b77e23db6e890353e22632ba630f" }, "userAddress": { "type": "string", "description": "User wallet address (required for tx building)", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } }, "SwapResponse": { "type": "object", "required": [ "userAddress", "quote", "toAddress", "calldata" ], "properties": { "calldata": { "type": "string", "description": "ABI-encoded Router.swap() calldata (hex encoded)", "example": "0x12345678" }, "quote": { "$ref": "#/components/schemas/QuoteResponse" }, "toAddress": { "type": "string", "description": "Router contract address", "example": "0xf4087AFfE358c1f267Cca84293abB89C4BD10712" }, "transactionExplanations": { "type": "array", "items": { "type": "string" }, "description": "Human-readable description for each transaction", "example": [ "Approve USDC spending", "Execute swap" ], "nullable": true }, "transactions": { "type": "array", "items": { "type": "object" }, "description": "Transactions to execute (approve + swap)", "nullable": true }, "txCostNative": { "type": "string", "description": "Estimated gas cost in native token (wei)", "example": "500000000000000", "nullable": true }, "txCostUsd": { "type": "number", "format": "double", "description": "Estimated gas cost in USD", "example": 1.75, "nullable": true }, "userAddress": { "type": "string", "description": "User wallet address", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } }, "SwapStep": { "type": "object", "required": [ "poolAddress", "dexName", "poolFee", "tokenIn", "tokenOut", "amountIn", "amountOut" ], "properties": { "amountIn": { "type": "string", "description": "Amount of input token in wei", "example": "1000000000000000000" }, "amountOut": { "type": "string", "description": "Amount of output token in wei", "example": "3500000000" }, "dexName": { "type": "string", "description": "DEX name (e.g., \"Uniswap V3\")", "example": "Uniswap V3" }, "poolAddress": { "type": "string", "description": "Pool contract address", "example": "0x1234567890123456789012345678901234567890" }, "poolFee": { "type": "number", "format": "double", "description": "Pool fee tier (e.g., 0.003 = 0.3%)", "example": 0.003 }, "tokenIn": { "type": "string", "description": "Input token address for this step", "example": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, "tokenOut": { "type": "string", "description": "Output token address for this step", "example": "0xb88339cb7199b77e23db6e890353e22632ba630f" } } }, "TokenInfo": { "type": "object", "required": [ "address", "symbol", "name", "decimals", "priceUsd" ], "properties": { "address": { "type": "string", "description": "Token contract address", "example": "0xb88339cb7199b77e23db6e890353e22632ba630f" }, "decimals": { "type": "integer", "format": "int32", "description": "Token decimals", "example": 18, "minimum": 0 }, "name": { "type": "string", "description": "Token name (e.g., \"Wrapped Ether\")", "example": "Wrapped Ether" }, "priceUsd": { "type": "number", "format": "double", "description": "Current USD price per whole token", "example": 3500 }, "symbol": { "type": "string", "description": "Token symbol (e.g., \"WETH\")", "example": "WETH" } } }, "V1RebalanceRequest": { "type": "object", "required": [ "userAddress", "positionManager", "positionId" ], "properties": { "approveMax": { "type": "boolean", "description": "If true, approve unlimited amount for NFT operations", "example": false }, "excludedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to exclude (see /v1/sources endpoint)", "example": [ 3 ], "nullable": true }, "includedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to include exclusively (see /v1/sources endpoint)", "example": [ 1, 2 ], "nullable": true }, "partnerFeeBps": { "type": "integer", "format": "int32", "description": "Partner fee in basis points (100 = 1%, max 100)", "example": 10, "minimum": 0 }, "poolAddress": { "type": "string", "description": "Optional: Target pool address (looked up from position if not provided)", "example": "0x1234567890123456789012345678901234567890", "nullable": true }, "positionId": { "type": "string", "description": "Position NFT ID to rebalance", "example": "12345" }, "positionManager": { "type": "string", "description": "NFT position manager contract address", "example": "0x1234567890123456789012345678901234567890" }, "slippage": { "type": "number", "format": "double", "description": "Slippage tolerance as decimal (0.01 = 1%). Default: 0.005", "example": 0.01 }, "stake": { "type": "boolean", "description": "If true, stake the new LP position after minting", "example": false }, "tickLower": { "type": "integer", "format": "int32", "description": "New lower tick for the position. If None, auto-centers around current tick.", "example": -887220, "nullable": true }, "tickUpper": { "type": "integer", "format": "int32", "description": "New upper tick for the position. If None, auto-centers around current tick.", "example": 887220, "nullable": true }, "userAddress": { "type": "string", "description": "User wallet address (position owner)", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } }, "V1RebalanceResponse": { "type": "object", "required": [ "userAddress", "quote", "toAddress", "swapLogicAddress", "calldata", "blockNumber" ], "properties": { "blockNumber": { "type": "integer", "format": "int64", "description": "Block number at which response was calculated", "example": 12345678, "minimum": 0 }, "calldata": { "type": "string", "description": "ABI-encoded Router.swap() calldata (hex encoded)", "example": "0x12345678" }, "quote": { "$ref": "#/components/schemas/RebalanceQuoteResponse" }, "swapLogicAddress": { "type": "string", "description": "SwapLogic contract address", "example": "0xE05247665778F1E698B6Ed564070e6056E8EEc82" }, "toAddress": { "type": "string", "description": "Router contract address", "example": "0xf4087AFfE358c1f267Cca84293abB89C4BD10712" }, "transactionExplanations": { "type": "array", "items": { "type": "string" }, "description": "Human-readable description for each transaction", "example": [ "Approve NFT position manager", "Execute rebalance" ], "nullable": true }, "transactions": { "type": "array", "items": { "type": "object" }, "description": "Transactions to execute (approve + rebalance)", "nullable": true }, "txCostNative": { "type": "string", "description": "Estimated gas cost in native token (wei)", "example": "500000000000000", "nullable": true }, "txCostUsd": { "type": "number", "format": "double", "description": "Estimated gas cost in USD", "example": 1.75, "nullable": true }, "userAddress": { "type": "string", "description": "User wallet address", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } }, "V1ZapRequest": { "type": "object", "required": [ "userAddress", "tokenIn", "amountIn", "poolAddress", "positionManager", "tickLower", "tickUpper" ], "properties": { "amountIn": { "type": "string", "description": "Amount of token_in to zap (in wei)", "example": "1000000000000000000" }, "approveMax": { "type": "boolean", "description": "If true, approve unlimited amount", "example": false }, "constraints": { "type": "array", "items": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string" } ] } }, "description": "Additional token constraints for routing" }, "excludedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to exclude (see /v1/sources endpoint)", "example": [ 3 ], "nullable": true }, "includedSources": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 }, "description": "DEX source IDs to include exclusively (see /v1/sources endpoint)", "example": [ 1, 2 ], "nullable": true }, "partnerFeeBps": { "type": "integer", "format": "int32", "description": "Partner fee in basis points (100 = 1%, max 100)", "example": 10, "minimum": 0 }, "poolAddress": { "type": "string", "description": "Target Uniswap V3 pool address", "example": "0x3e69297ae794011970256623b4ab68324983b9ed" }, "positionId": { "type": "string", "description": "Existing position ID (for increasing liquidity). If None, mints new position.", "example": "12345", "nullable": true }, "positionManager": { "type": "string", "description": "NFT position manager contract address", "example": "0xE7ffA0ee20Deb1613489556062Fa8cec690C3c02" }, "slippage": { "type": "number", "format": "double", "description": "Slippage tolerance as decimal (0.01 = 1%). Default: 0.005", "example": 0.01 }, "stake": { "type": "boolean", "description": "If true, stake the LP position after minting", "example": false }, "tickLower": { "type": "integer", "format": "int32", "description": "Lower tick of the position range", "example": -887220 }, "tickUpper": { "type": "integer", "format": "int32", "description": "Upper tick of the position range", "example": 887220 }, "tokenIn": { "type": "string", "description": "Input token address (use 0xeeee...eeee for native token)", "example": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, "userAddress": { "type": "string", "description": "User wallet address", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } }, "example": { "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045", "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee", "amountIn": "1000000000000000000", "poolAddress": "0x3e69297ae794011970256623b4ab68324983b9ed", "positionManager": "0xE7ffA0ee20Deb1613489556062Fa8cec690C3c02", "tickLower": -887220, "tickUpper": 887220, "slippage": 0.01 } }, "V1ZapResponse": { "type": "object", "required": [ "userAddress", "quote", "toAddress", "swapLogicAddress", "calldata", "blockNumber" ], "properties": { "blockNumber": { "type": "integer", "format": "int64", "description": "Block number at which response was calculated", "example": 12345678, "minimum": 0 }, "calldata": { "type": "string", "description": "ABI-encoded Router.swap() calldata (hex encoded)", "example": "0x12345678" }, "quote": { "$ref": "#/components/schemas/ZapQuoteResponse" }, "swapLogicAddress": { "type": "string", "description": "SwapLogic contract address", "example": "0xE05247665778F1E698B6Ed564070e6056E8EEc82" }, "toAddress": { "type": "string", "description": "Router contract address", "example": "0xf4087AFfE358c1f267Cca84293abB89C4BD10712" }, "transactionExplanations": { "type": "array", "items": { "type": "string" }, "description": "Human-readable description for each transaction", "example": [ "Approve USDC spending", "Execute zap" ], "nullable": true }, "transactions": { "type": "array", "items": { "type": "object" }, "description": "Transactions to execute (approve + swap)", "nullable": true }, "txCostNative": { "type": "string", "description": "Estimated gas cost in native token (wei)", "example": "500000000000000", "nullable": true }, "txCostUsd": { "type": "number", "format": "double", "description": "Estimated gas cost in USD", "example": 1.75, "nullable": true }, "userAddress": { "type": "string", "description": "User wallet address", "example": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045" } } }, "ZapQuoteResponse": { "type": "object", "required": [ "tokenIn", "amountIn", "poolAddress", "slippage", "tokens", "swaps", "sourcesAndSinks", "liquidityAmount", "blockNumber" ], "properties": { "amountIn": { "type": "string", "description": "Input amount in wei", "example": "1000000000000000000" }, "blockNumber": { "type": "integer", "format": "int64", "description": "Block number at which quote was calculated", "example": 12345678, "minimum": 0 }, "liquidityAmount": { "type": "string", "description": "Expected liquidity amount to be minted", "example": "1000000000000000000" }, "partnerFeeBps": { "type": "integer", "format": "int32", "description": "Partner fee in basis points (100 = 1%)", "example": 10, "nullable": true, "minimum": 0 }, "partnerId": { "type": "integer", "format": "int32", "description": "Partner ID (from API key)", "example": 1, "nullable": true, "minimum": 0 }, "poolAddress": { "type": "string", "description": "Target pool address", "example": "0x1234567890123456789012345678901234567890" }, "slippage": { "type": "number", "format": "double", "description": "Applied slippage tolerance", "example": 0.01 }, "sourcesAndSinks": { "type": "array", "items": { "type": "array", "items": { "allOf": [ { "type": "string" }, { "type": "string" } ] } }, "description": "Token amounts by address (negative = spend, positive = receive)" }, "swaps": { "type": "array", "items": { "$ref": "#/components/schemas/SwapStep" }, "description": "Detailed swap steps" }, "tokenIn": { "type": "string", "description": "Input token address", "example": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" }, "tokens": { "type": "array", "items": { "$ref": "#/components/schemas/TokenInfo" }, "description": "All tokens involved in the operation" } } }, "ChainInfo": { "type": "object", "required": [ "chainId", "name" ], "properties": { "chainId": { "type": "integer", "format": "int64", "description": "EVM chain ID", "example": 999, "minimum": 0 }, "name": { "type": "string", "description": "Human-readable chain name", "example": "HyperEVM" } } }, "ChainsResponse": { "type": "object", "required": [ "meta", "kyoAg" ], "properties": { "meta": { "type": "object", "required": [ "chains" ], "properties": { "chains": { "type": "array", "items": { "$ref": "#/components/schemas/ChainInfo" }, "description": "Chains available in Meta Aggregator competitions" } } }, "kyoAg": { "type": "object", "required": [ "chains" ], "properties": { "chains": { "type": "array", "items": { "$ref": "#/components/schemas/ChainInfo" }, "description": "Chains currently supported by `/v1/*` KYO aggregator endpoints" } } } }, "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": "Swap", "description": "# Token Swap\n\nThe core feature of KYO.ag - aggregates liquidity from multiple DEXs to find optimal swap routes.\n\n## Supported Chains\n\n| Chain | Chain ID | Status |\n|-------|----------|--------|\n| HyperEVM | 999 | ✅ Live |\n| Soneium | 1868 | ✅ Live |\n\n## How It Works\n\n1. **Route Discovery**: Explores all available pools for possible paths\n2. **Price Optimization**: Selects optimal route considering slippage and gas costs\n3. **Split Routing**: Splits large orders across multiple pools to minimize price impact\n\n## Modes\n\n| Mode | Parameter | Use Case |\n|------|-----------|----------|\n| **Sell** | `amountIn` | Sell exact amount of input token |\n| **Buy** | `amountOut` | Buy exact amount of output token |\n\n> [!tip]\n> For large swaps, use `/v1/quote` first to preview expected results.\n" }, { "name": "Zap", "description": "# Single-Sided LP (Zap)\n\nEnter Uniswap V3 LP positions with just a single token.\n\n## Supported Chains\n\n| Chain | Chain ID | Status |\n|-------|----------|--------|\n| HyperEVM | 999 | ✅ Live |\n| Soneium | 1868 | ✅ Live |\n\n## Problem Solved\n\n**Traditional LP entry process:**\n1. Prepare Token A and Token B in exact ratio\n2. Calculate ratio matching current tick\n3. Manually execute swap\n4. Mint LP position\n\n**With Zap:**\n- Deposit any token → Done!\n\n## Features\n\n| Feature | Description |\n|---------|-------------|\n| **Single Token Entry** | Enter LP with just one token |\n| **Auto Ratio** | Automatically calculates optimal ratio for tick range |\n| **Position Increase** | Add liquidity to existing positions |\n" }, { "name": "Rebalance", "description": "# LP Position Rebalancing\n\nAdjust the tick range of existing Uniswap V3 positions.\n\n## Supported Chains\n\n| Chain | Chain ID | Status |\n|-------|----------|--------|\n| HyperEVM | 999 | ✅ Live |\n| Soneium | 1868 | ✅ Live |\n\n## When to Rebalance\n\n| Situation | Action |\n|-----------|--------|\n| Price out of range | Re-center around current price |\n| Want higher yields | Concentrate to narrower range |\n| Reduce risk | Spread to wider range |\n\n## Benefits vs Manual\n\n| | Manual | Rebalance API |\n|--|--------|---------------|\n| Transactions | 4+ | 1 |\n| Ratio calculation | Manual | Automatic |\n| Gas cost | High | Optimized |\n| Fee collection | Separate | Included |\n\n> [!important]\n> When rebalancing, the old NFT is burned and a new NFT is minted.\n" }, { "name": "Sources", "description": "# DEX Sources\n\nQuery the list of DEXs supported by KYO.ag, and include or exclude specific DEXs.\n\n## Supported Chains\n\n| Chain | Chain ID | Status |\n|-------|----------|--------|\n| HyperEVM | 999 | ✅ Live |\n| Soneium | 1868 | ✅ Live |\n\n## Filtering Options\n\n```json\n// Use only specific DEXs\n{ \"includedSources\": [1, 2] }\n\n// Exclude specific DEXs\n{ \"excludedSources\": [3] }\n```\n\n## Use Cases\n\n| Use Case | Example |\n|----------|---------|\n| Testing | Verify routing through specific DEX |\n| Preference | Use only trusted DEXs |\n| Debugging | Temporarily exclude problematic DEX |\n" }, { "name": "Chains", "description": "# Supported Chains\n\nDiscover currently supported chain IDs dynamically.\n\n- `GET /chains` returns:\n - `kyoAg.chains`: chains currently supported by `/v1/*` endpoints\n - `meta.chains`: chains available in Meta Aggregator competitions\n\nUse this endpoint instead of hardcoding chain IDs in clients." } ] }