> ## Documentation Index
> Fetch the complete documentation index at: https://docs.leokit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quote Endpoints

> Get swap quotes from multiple protocols and stream real-time updates

## GET /leokit/quote

Get swap quotes from multiple protocols in a single request.

### Request Parameters

| Parameter            | Type   | Required | Description                                                  |
| -------------------- | ------ | -------- | ------------------------------------------------------------ |
| `from_asset`         | string | Yes      | Source asset in format `CHAIN.SYMBOL-ADDRESS`                |
| `to_asset`           | string | Yes      | Destination asset in format `CHAIN.SYMBOL-ADDRESS`           |
| `amount`             | string | Yes      | Amount to swap in base units (e.g., "1000000" for 1 USDC)    |
| `destination`        | string | Yes      | Recipient address for the output asset                       |
| `origin`             | string | No       | Source address (optional, some protocols use for validation) |
| `affiliate`          | string | No       | Affiliate address for revenue sharing                        |
| `slippage_bps`       | number | No       | Slippage tolerance in basis points (default: 150 = 1.5%)     |
| `streaming_interval` | number | No       | Streaming swap interval for THORChain/MAYA (default: 3)      |
| `streaming_quantity` | number | No       | Number of streaming swap chunks (default: 1)                 |

### Response Format

**Status Code:** `200 OK`

```json theme={null}
{
  "quotes": [
    {
      "protocol": "thorchain",
      "data": {
        "expected_amount_out": "1985000000",
        "total_swap_seconds": 180,
        "fees": [
          {
            "type": "Affiliate Fee",
            "asset": "BTC.BTC",
            "amount": 0.00003,
            "usd": 1.2
          },
          {
            "type": "Outbound Fee",
            "asset": "ETH.ETH",
            "amount": 0.001,
            "usd": 3.5
          },
          {
            "type": "Network Fee",
            "asset": "THOR.RUNE",
            "amount": 0.02,
            "usd": 0.08
          }
        ],
        "route": [
          "BTC.BTC",
          "THOR.RUNE",
          "ETH.USDC-0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
        ],
        "in_asset_decimal": "8",
        "out_asset_decimal": "6",
        "out_asset_price": "1.00000",
        "from_asset_price": "98500.00000",
        "recommended_slippage": 150
      },
      "expectedAmountOutNum": 1985.0,
      "totalFeesUsd": 4.78,
      "totalSwapSeconds": 180,
      "flags": ["OPTIMAL", "CHEAPEST"]
    },
    {
      "protocol": "chainflip",
      "data": {
        "expected_amount_out": "1983500000",
        "total_swap_seconds": 60,
        "fees": [
          {
            "type": "Deposit Fee",
            "asset": "BTC.BTC",
            "amount": 0.00001,
            "usd": 0.98
          },
          {
            "type": "Network Fee",
            "asset": "BTC.BTC",
            "amount": 0.000015,
            "usd": 1.47
          },
          {
            "type": "Broadcast Fee",
            "asset": "ETH.USDC",
            "amount": 2.5,
            "usd": 2.5
          }
        ],
        "route": ["BTC", "USDC"],
        "in_asset_decimal": "8",
        "out_asset_decimal": "6",
        "out_asset_price": "1.00000",
        "from_asset_price": "98500.00000"
      },
      "expectedAmountOutNum": 1983.5,
      "totalFeesUsd": 4.95,
      "totalSwapSeconds": 60,
      "flags": ["FASTEST"]
    }
  ],
  "timestamp": "2026-01-15T12:34:56.789Z",
  "quote_id": "01936b4a-7c8e-7890-abcd-ef1234567890"
}
```

### Helper Fields (top-level on each quote)

The server adds these fields to every quote to simplify client-side sorting and filtering. They are computed once per response by the optimal-route ranker.

| Field                  | Type      | Description                                                              |
| ---------------------- | --------- | ------------------------------------------------------------------------ |
| `expectedAmountOutNum` | number    | `data.expected_amount_out` parsed and scaled by destination decimals     |
| `totalFeesUsd`         | number    | Sum of all `fees[].usd` for this quote                                   |
| `totalSwapSeconds`     | number    | `data.total_swap_seconds` (mirrored at top level for consistent sorting) |
| `flags`                | string\[] | Performance tags (see below). Empty array if no flag applies             |

## Quote Flags

Quotes are automatically tagged with performance indicators:

* **FASTEST** - Lowest `totalSwapSeconds`
* **CHEAPEST** - Lowest `totalFeesUsd`
* **OPTIMAL** - Highest `expectedAmountOutNum` (tie-broken by fees, then speed)
* **BEST\_OUTPUT** - Highest output across all quotes (alias of OPTIMAL on the winning quote)

### Fee Breakdown Examples

Each quote includes a detailed fee breakdown with the following structure:

```json theme={null}
{
  "type": "Fee Type",
  "asset": "CHAIN.SYMBOL",
  "amount": 0.001,
  "usd": 3.5
}
```

**Common Fee Types:**

* **Affiliate Fee** - Revenue sharing with integrators
* **Outbound Fee** - Blockchain network fee for sending output
* **Network Fee** - Protocol or router fee
* **Deposit Fee** - Fee for depositing into protocol
* **Broadcast Fee** - Fee for broadcasting transaction to destination chain

## Error Responses

**Missing Required Parameters (400)**

```json theme={null}
{
  "error": "Missing required params: from_asset, to_asset, amount",
  "status": 400
}
```

**No Quotes Available (404)**

```json theme={null}
{
  "error": "No quotes available from any protocol",
  "status": 404
}
```

**Internal Server Error (500)**

```json theme={null}
{
  "error": "Internal server error",
  "details": "Error message",
  "status": 500
}
```

## GET /leokit/streaming-quotes

Stream quotes as Server-Sent Events (SSE) for real-time updates as protocols respond.

### Request Parameters

Same as `/leokit/quote` endpoint.

### Response Format

**Content-Type:** `text/event-stream`

**Event Stream:**

```
data: {"type":"init","quote_id":"01936b4a-7c8e-7890-abcd-ef1234567890","timestamp":"2026-01-15T12:34:56.789Z","total":6}

data: {"type":"quote","protocol":"chainflip","data":{"expected_amount_out":"1983500000",...}}

data: {"type":"quote","protocol":"thorchain","data":{"expected_amount_out":"1985000000",...}}

data: {"type":"quote","protocol":"relay","data":{"expected_amount_out":"1980000000",...}}

data: {"type":"final","quotes":[...],"timestamp":"2026-01-15T12:34:58.123Z","quote_id":"01936b4a-7c8e-7890-abcd-ef1234567890"}

data: {"type":"finished"}
```

### Event Types

| Type       | Description                                               |
| ---------- | --------------------------------------------------------- |
| `init`     | Initial event with quote\_id and total expected protocols |
| `quote`    | Individual quote as it resolves from each protocol        |
| `final`    | Aggregated final result with all quotes and flags         |
| `finished` | Stream completion signal                                  |
| `error`    | Error occurred (e.g., no quotes available)                |

### Stream Characteristics

* **Safety Timeout:** 7 seconds maximum
* **Connection:** Keep-alive with heartbeat
* **Cache-Control:** `no-cache`
* **Client Disconnect:** Gracefully handled, quote still logged to database

### Error Event

```
data: {"type":"error","data":"No quotes available from any protocol"}
```