# KYO.ag API - Complete Documentation

> KYO.ag is a multi-chain DEX aggregator. Built in Rust for speed, with mathematically optimal routing.

## Base URL

```
https://api.kyo.ag/{chainId}/v1/{endpoint}
```

## Supported Chains

| Chain | Chain ID | Example |
|-------|----------|---------|
| HyperEVM | 999 | `https://api.kyo.ag/999/v1/quote` |
| Soneium | 1868 | `https://api.kyo.ag/1868/v1/quote` |

For dynamic discovery of the latest supported chain IDs:

```bash
curl https://api.kyo.ag/chains
```

- `kyoAg.chains`: chains currently supported by Aggregator endpoints (`/v1/*`)
- `meta.chains`: chains available for Meta Aggregator competitions

## 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
- **Single-Sided LP**: Zap into Uniswap V3 positions with any token
- **Position Rebalancing**: Adjust LP tick ranges without manual withdrawals

## Authentication

Authorization is optional for all endpoints.
Visit https://portal.kyo.ag to generate your API key for higher rate limits.

```
Authorization: Bearer YOUR_API_KEY
```

Calls without an API key are supported.
Partners with an API key can receive higher rate limits (up to 10x) and revshare.

Visit [portal.kyo.ag](https://portal.kyo.ag) to generate your API key.

---

## GET /chains

Get supported chain IDs for both Aggregator and Meta Aggregator APIs.

### Response

| Field | Type | Description |
|-------|------|-------------|
| meta.chains | ChainInfo[] | Chain IDs available for Meta Aggregator competitions |
| kyoAg.chains | ChainInfo[] | Chain IDs currently supported by KYO Aggregator `/v1/*` endpoints |

### Example

```bash
curl https://api.kyo.ag/chains
```

---

## POST /v1/quote

Get optimal swap route and expected amounts without building transaction data.

**Supported Chains:** HyperEVM (999), Soneium (1868)

### Modes
- **Sell mode**: Specify `amountIn` to sell a fixed amount of input token
- **Buy mode**: Specify `amountOut` to buy a fixed amount of output token

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| tokenIn | string | Yes | Input token address. Use `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` for native token |
| tokenOut | string | Yes | Output token address |
| amountIn | string | Conditional | Input amount in wei (required for sell mode) |
| amountOut | string | Conditional | Output amount in wei (required for buy mode) |
| slippage | number | No | Slippage tolerance as decimal. Default: 0.005 (0.5%). Example: 0.01 = 1% |
| partnerFeeBps | integer | No | Partner fee in basis points. 100 = 1%. Max: 100 |
| includedSources | integer[] | No | DEX source IDs to include exclusively |
| excludedSources | integer[] | No | DEX source IDs to exclude |

### Response

| Field | Type | Description |
|-------|------|-------------|
| tokenIn | string | Input token address |
| tokenOut | string | Output token address |
| amountIn | string | Input amount in wei |
| amountOut | string | Expected output amount in wei (before slippage) |
| minOutputAmount | string | Minimum output after slippage (sell mode) |
| maxInputAmount | string | Maximum input after slippage (buy mode) |
| priceImpactPct | number? | Estimated price impact percentage. May be `null` when unavailable |
| slippage | number | Applied slippage tolerance |
| swaps | SwapStep[] | Detailed swap route steps |
| tokens | TokenInfo[] | All tokens in the route |
| blockNumber | integer | Block number at quote time |

### Example

```bash
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",
    "slippage": 0.01
  }'
```

---

## POST /v1/swap

Get optimal swap route with ready-to-sign transaction data.

**Supported Chains:** HyperEVM (999), Soneium (1868)

### Request Body

All fields from `/v1/quote` plus:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| userAddress | string | Yes | Wallet address executing the swap |
| approveMax | boolean | No | If true, approve unlimited spending |

### Response

| Field | Type | Description |
|-------|------|-------------|
| userAddress | string | User wallet address |
| quote | QuoteResponse | Complete quote information, including `priceImpactPct` when available |
| toAddress | string | Router contract address |
| calldata | string | ABI-encoded transaction data (hex) |
| transactions | object[] | Array of transactions (approve + swap) |
| transactionExplanations | string[] | Human-readable tx descriptions |
| txCostNative | string | Estimated gas in native token wei |
| txCostUsd | number | Estimated gas in USD |

### Transaction Execution

**For native token input:**
Send transaction with value = `amountIn` (sell) or `maxInputAmount` (buy)

**For ERC20 input:**
1. Execute approve transaction first (if provided)
2. Execute swap transaction

### Example

```bash
curl -X POST https://api.kyo.ag/999/v1/swap \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f",
    "amountIn": "1000000000000000000",
    "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "slippage": 0.01
  }'
```

---

## POST /v1/zap

Single-sided liquidity provision into Uniswap V3 positions.

**Supported Chains:** HyperEVM (999), Soneium (1868)

### Request Body

| 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 address |
| 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 ID to increase liquidity |
| slippage | number | No | Slippage tolerance. Default: 0.005 |
| partnerFeeBps | integer | No | Partner fee in basis points |
| stake | boolean | No | Stake LP after minting |
| approveMax | boolean | No | Approve unlimited spending |
| constraints | array | No | Additional token constraints for routing |
| includedSources | integer[] | No | DEX source IDs to include exclusively |
| excludedSources | integer[] | No | DEX source IDs to exclude |

### Response

| Field | Type | Description |
|-------|------|-------------|
| userAddress | string | User wallet address |
| quote | ZapQuoteResponse | Quote with liquidityAmount, tokens, swaps |
| toAddress | string | Router contract address |
| swapLogicAddress | string | SwapLogic contract address |
| calldata | string | ABI-encoded transaction data (hex) |
| blockNumber | integer | Block number at quote time |
| transactions | object[] | Array of transactions (approve + zap) |
| transactionExplanations | string[] | Human-readable tx descriptions |
| txCostNative | string | Estimated gas in native token wei |
| txCostUsd | number | Estimated gas in USD |

### Example

```bash
curl -X POST https://api.kyo.ag/999/v1/zap \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "amountIn": "1000000000000000000",
    "poolAddress": "0x3e69297ae794011970256623b4ab68324983b9ed",
    "positionManager": "0xE7ffA0ee20Deb1613489556062Fa8cec690C3c02",
    "tickLower": -887220,
    "tickUpper": 887220
  }'
```

---

## POST /v1/rebalance

Rebalance a Uniswap V3 LP position with a new tick range.

**Supported Chains:** HyperEVM (999), Soneium (1868)

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| userAddress | string | Yes | Position owner wallet address |
| positionManager | string | Yes | NFT position manager contract |
| positionId | string | Yes | Position NFT ID to rebalance |
| tickLower | integer | No | New lower tick. Auto-centers if not provided |
| tickUpper | integer | No | New upper tick. Auto-centers if not provided |
| poolAddress | string | No | Target pool (looked up from position if omitted) |
| slippage | number | No | Slippage tolerance. Default: 0.005 |
| partnerFeeBps | integer | No | Partner fee in basis points |
| stake | boolean | No | Stake new position after minting |
| approveMax | boolean | No | Approve unlimited NFT operations |
| includedSources | integer[] | No | DEX source IDs to include exclusively |
| excludedSources | integer[] | No | DEX source IDs to exclude |

### Response

| Field | Type | Description |
|-------|------|-------------|
| userAddress | string | User wallet address |
| quote | RebalanceQuoteResponse | Quote with positionId, tickLower/Upper, liquidityAmount, logPriceImpact |
| toAddress | string | Router contract address |
| swapLogicAddress | string | SwapLogic contract address |
| calldata | string | ABI-encoded transaction data (hex) |
| blockNumber | integer | Block number at quote time |
| transactions | object[] | Array of transactions (approve + rebalance) |
| transactionExplanations | string[] | Human-readable tx descriptions |
| txCostNative | string | Estimated gas in native token wei |
| txCostUsd | number | Estimated gas in USD |

### Example

```bash
curl -X POST https://api.kyo.ag/999/v1/rebalance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "positionManager": "0xE7ffA0ee20Deb1613489556062Fa8cec690C3c02",
    "positionId": "12345",
    "tickLower": -60000,
    "tickUpper": 60000
  }'
```

---

## GET /v1/sources

List available DEX sources for filtering. No authentication required.

**Supported Chains:** HyperEVM (999), Soneium (1868)

### Response

| Field | Type | Description |
|-------|------|-------------|
| chainId | integer | Current chain ID |
| sources | SourceInfo[] | Available DEX sources |

### Example

```bash
curl https://api.kyo.ag/999/v1/sources
```

---

## Common Types

### SwapStep
```json
{
  "poolAddress": "0x1234...",
  "dexName": "Uniswap V3",
  "poolFee": 0.003,
  "tokenIn": "0xeeee...",
  "tokenOut": "0xb883...",
  "amountIn": "1000000000000000000",
  "amountOut": "3500000000"
}
```

### TokenInfo
```json
{
  "address": "0xb883...",
  "symbol": "WETH",
  "name": "Wrapped Ether",
  "decimals": 18,
  "priceUsd": 3500.0
}
```

### ErrorResponse
```json
{
  "error": "NO_ROUTE_FOUND",
  "message": "No route found between the specified tokens"
}
```

Error codes: `INVALID_TOKEN`, `INVALID_AMOUNT`, `NO_ROUTE_FOUND`, `INSUFFICIENT_LIQUIDITY`, `INVALID_PARAMETERS`, `INTERNAL_ERROR`

---

## Rate Limits

- Without API key:
  - Aggregator APIs (`/v1/*`): 60 requests/minute
  - Meta Aggregator APIs (`/competitions`, `/quotes`, `/swap`): 20 requests/minute
- With API key:
  - Up to 10x of the above limits
- Limits are subject to change
- Abusive traffic or persistently low swap-to-quote ratios may be throttled

---
---

# Meta Aggregator API

> Compare quotes from multiple DEX aggregators and execute the best swap through a competition model.

## Base URL

```
https://api.kyo.ag
```

To choose a valid `chainId` for competitions, call `GET /chains` and use values from `meta.chains`.

## How It Works

1. Create a Competition — Submit swap parameters (chain, tokens, amount, slippage). Returns `competitionId` and list of available aggregators.
2. Fetch Quotes — Query each aggregator using the `competitionId` to collect pricing quotes. Run in parallel.
3. Compare Results — Use the results endpoint to see all quotes ranked.
4. Execute Swap — Call `/swap` with the winning aggregator to get transaction calldata.

Competitions have a short TTL. Once expired, requests return `410 Gone`.

## Authentication

Authorization is optional for all Meta Aggregator endpoints.

```
Authorization: Bearer YOUR_API_KEY
```

Without an API key, Meta Aggregator endpoints are limited to 20 requests/minute.
With an API key, limits are up to 10x higher and partners may receive revshare.

Visit [portal.kyo.ag](https://portal.kyo.ag) to generate your API key.

---

## POST /competitions

Create a new competition.

### Request Body

| 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%) |
| tokenInDecimals | integer | No | Decimals of tokenIn (default: 18) |

### Response

| Field | Type | Description |
|-------|------|-------------|
| competitionId | string | Unique competition identifier |
| availableAggregators | string[] | List of aggregator names to query |
| chainId | integer | Chain ID |
| expiresAt | string | ISO 8601 expiration timestamp |

### Example

```bash
curl -X POST https://api.kyo.ag/competitions \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": 999,
    "tokenIn": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
    "tokenOut": "0xb88339cb7199b77e23db6e890353e22632ba630f",
    "amountIn": "1000000000000000000",
    "userAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "slippage": 0.01
  }'
```

---

## POST /quotes?aggregator={agg}&competitionId={id}

Fetch a pricing quote from a specific aggregator. No request body needed.

### Response

| Field | Type | Description |
|-------|------|-------------|
| aggregator | string | Aggregator name |
| tokenIn | string | Input token address |
| tokenOut | string | Output token address |
| amountIn | string | Input amount in wei |
| amountOut | string | Output amount in wei |
| gasEstimate | string? | Estimated gas cost |
| competitionId | string | Competition ID |

---

## GET /competitions/{id}/results

Get all quotes for a competition, ranked by output amount.

### Response

| Field | Type | Description |
|-------|------|-------------|
| competitionId | string | Competition ID |
| chainId | integer | Chain ID |
| tokenIn | string | Input token address |
| tokenOut | string | Output token address |
| amountIn | string | Input amount in wei |
| quotes | NormalizedQuote[] | Array of quotes sorted by amountOut |

---

## POST /swap?aggregator={agg}&competitionId={id}

Get transaction calldata for the chosen aggregator. No request body needed.

### Response

| Field | Type | Description |
|-------|------|-------------|
| aggregator | string | Aggregator name |
| tokenIn | string | Input token address |
| tokenOut | string | Output token address |
| amountIn | string | Input amount in wei |
| amountOut | string | Output amount in wei |
| to | string | Contract to send the tx to |
| data | string | Calldata for the swap tx |
| value | string | Native value to send with tx (for native token sells) |
| allowanceTarget | string | Contract that needs token approval (may differ from `to`) |
| competitionId | string | Competition ID |

### Transaction Execution

- For native token input: send `value` with the transaction
- For ERC20 input: approve `allowanceTarget` first, then send tx to `to`

---

## Meta Aggregator Error Handling

| HTTP Status | Description |
|-------------|-------------|
| 400 | Bad request - invalid parameters |
| 401 | Unauthorized - missing or invalid API key |
| 404 | Competition not found |
| 410 | Competition expired - create a new one |

---

# Cross-Chain API

> Request executable cross-chain quotes, submit the returned user transactions, and poll lifecycle status.

## Base URL

```
https://cross-chain-api.kyo.ag
```

Authorization is optional for public endpoints.
Calls without an API key are supported.
Partners with an API key can receive higher RPS limits (up to 10x) and revshare.
Visit [portal.kyo.ag](https://portal.kyo.ag) to generate your API key.

## GET /v1/chains

List chains currently supported by the Cross-Chain API.

## GET /v1/currencies

List supported currencies for the requested chain IDs.

Query parameter:

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| chainIds | string | Yes | Comma-separated chain IDs, for example `1,8453` |

## POST /v1/quote

Create an executable cross-chain quote.

### Request Body

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| userAddress | string | Yes | Wallet that signs the returned transactions |
| recipientAddress | string | No | Destination recipient. Defaults to `userAddress` |
| originChainId | integer | Yes | Source chain ID |
| destinationChainId | integer | Yes | Destination chain ID |
| tokenIn | string | Yes | Source token address on `originChainId` |
| tokenOut | string | Yes | Destination token address on `destinationChainId` |
| amountIn | string | Yes | Exact input amount in raw token units |
| slippage | number | Yes | Slippage as a decimal fraction |
| partnerFeeBps | integer | No | Optional partner fee in basis points |

### Response

| Field | Type | Description |
|-------|------|-------------|
| userAddress | string | Wallet that signs returned transactions |
| requestId | string | Status tracking ID |
| originChainId | integer | Source chain ID |
| destinationChainId | integer | Destination chain ID |
| quote | object | Amounts, slippage, and partner fee details |
| transactions | object[] | User-signed transactions to submit in order |
| transactionExplanations | string[] | Human-readable descriptions aligned with `transactions` |
| timeEstimate | number | Estimated completion time in seconds |

## GET /v1/transactions/{sourceTxHash}

Poll transaction lifecycle status by source-chain transaction hash.

### Response

| Field | Type | Description |
|-------|------|-------------|
| requestId | string | Status tracking ID |
| status | object | Overall status label and kind |
| primaryTransaction | object | Primary transaction reference |
| updatedAt | string | ISO timestamp of the latest update |
| source | object | Source-side transfer and fee state |
| destination | object | Destination-side transfer and fee state |