> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/api-v1/endpoints/quote.md).

# Quote

```
POST /v1/quote
```

Quotes a same-chain swap or a cross-chain transfer and returns the best route as a single **step**, including the transaction for the user to sign. Swapper picks the best route among several liquidity sources and bridges, so `tool` is always `swapper` and `includedSteps` is always empty.

## Request body

A JSON object (`Content-Type: application/json`):

| Name          | Required      | Description                                                                                                                                                                                                                                                                                              |
| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fromChain`   | yes           | Source chain id or key (e.g. `8453` or `"base"`; Solana is `"mainnet-beta"` or `"solana"`).                                                                                                                                                                                                              |
| `toChain`     | yes           | Destination chain id or key. Same as `fromChain` for a swap.                                                                                                                                                                                                                                             |
| `fromToken`   | yes           | Source token address or symbol, as listed by [`GET /v1/tokens`](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#list-tokens).                                                                                                                                                         |
| `toToken`     | yes           | Destination token address or symbol, as listed by `GET /v1/tokens`.                                                                                                                                                                                                                                      |
| `fromAmount`  | yes           | Amount to send, as an integer string in the source token's smallest unit (`100000000` = 100 USDC).                                                                                                                                                                                                       |
| `fromAddress` | yes           | Sender. Must be an address of the source chain's ecosystem (EVM `0x` + 40 hex, Solana base58).                                                                                                                                                                                                           |
| `toAddress`   | no            | Recipient, an address of the destination chain's ecosystem. Defaults to `fromAddress`; **required** when the destination chain is in a different ecosystem than the source chain (e.g. EVM → Solana).                                                                                                    |
| `slippage`    | no            | Maximum slippage as a decimal fraction, `0` to `0.5`. Default `0.005` (0.5%).                                                                                                                                                                                                                            |
| `integrator`  | without a key | Your `integratorId`. Required without an API key. With a key you can omit it; if sent, it must be the key's integrator.                                                                                                                                                                                  |
| `fee`         | no            | Your [integrator fee](https://docs.swapper.finance/api-v1/integrator-fees.md) as a decimal fraction (`0.003` = 0.3%), charged on top of Swapper's fee and deducted from the input amount. Requires an API key. Maximum `0.03` unless agreed otherwise; whole basis points only (a multiple of `0.0001`). |

Authentication is optional — see [Authentication](https://docs.swapper.finance/api-v1/authentication.md). Quotes count against the **quote** [rate limit](https://docs.swapper.finance/api-v1/rate-limits.md).

## Example

100 USDC on Base → USDC on Arbitrum, with a 0.4% integrator fee:

```bash
curl -X POST "https://swapper.finance/api/v1/quote" \
  -H "x-swapper-api-key: $SWAPPER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "fromChain": 8453,
    "toChain": 42161,
    "fromToken": "USDC",
    "toToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "fromAmount": "100000000",
    "fromAddress": "0x1111111111111111111111111111111111111111",
    "slippage": 0.007,
    "fee": 0.004
  }'
```

## Response

```json
{
  "id": "dbadf637-0d70-4471-9cd8-fe993f8bc8e5",
  "type": "cross",
  "tool": "swapper",
  "toolDetails": {
    "key": "swapper",
    "name": "Swapper",
    "logoURI": "https://swapper.finance/logo.svg"
  },
  "action": {
    "fromChainId": "8453",
    "toChainId": "42161",
    "fromToken": {
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "chainId": "8453",
      "symbol": "USDC",
      "decimals": 6,
      "name": "USD Coin",
      "logoURI": "https://deposit.swapper.finance/assets/tokens/usdc.webp",
      "priceUSD": "1"
    },
    "toToken": {
      "address": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
      "chainId": "42161",
      "symbol": "USDC",
      "decimals": 6,
      "name": "USD Coin",
      "logoURI": "https://deposit.swapper.finance/assets/tokens/usdc.webp",
      "priceUSD": "0.9999"
    },
    "fromAmount": "100000000",
    "slippage": 0.007,
    "fromAddress": "0x1111111111111111111111111111111111111111",
    "toAddress": "0x1111111111111111111111111111111111111111"
  },
  "estimate": {
    "tool": "swapper",
    "fromAmount": "100000000",
    "fromAmountUSD": "100.00",
    "toAmount": "99300000",
    "toAmountMin": "98800000",
    "toAmountUSD": "99.29",
    "approvalAddress": "0x5f2c7a1e9b3d4c6a8e0f1b2d3c4e5f6a7b8c9d0e",
    "executionDuration": 45,
    "priceImpact": "0.0071",
    "feeCosts": [
      {
        "name": "Swapper fee",
        "description": "Swapper's fee for routing the transfer",
        "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6, "name": "USD Coin", "logoURI": "", "priceUSD": "1" },
        "amount": "100000",
        "amountUSD": "0.10",
        "percentage": "0.001",
        "included": true
      },
      {
        "name": "Integrator fee",
        "description": "Fee charged by the integrator",
        "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6, "name": "USD Coin", "logoURI": "", "priceUSD": "1" },
        "amount": "400000",
        "amountUSD": "0.40",
        "percentage": "0.004",
        "included": true
      },
      {
        "name": "Relayer fee",
        "description": "Paid to the relayer that fills the transfer on the destination chain",
        "token": { "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chainId": "8453", "symbol": "USDC", "decimals": 6, "name": "USD Coin", "logoURI": "", "priceUSD": "1" },
        "amount": "50000",
        "amountUSD": "0.05",
        "percentage": "0.0005",
        "included": true
      }
    ],
    "gasCosts": [
      {
        "type": "SEND",
        "price": "5000000",
        "estimate": "180000",
        "limit": "240000",
        "amount": "1200000000000",
        "amountUSD": "0.00",
        "token": { "address": "0x0000000000000000000000000000000000000000", "chainId": "8453", "symbol": "ETH", "decimals": 18, "name": "Ether", "logoURI": "", "priceUSD": "2500" }
      }
    ]
  },
  "includedSteps": [],
  "integrator": "acme",
  "transactionRequest": {
    "from": "0x1111111111111111111111111111111111111111",
    "to": "0x5f2c7a1e9b3d4c6a8e0f1b2d3c4e5f6a7b8c9d0e",
    "chainId": 8453,
    "data": "0x...",
    "value": "0x0",
    "gasLimit": "0x3a980"
  },
  "expiresAt": 1791054758
}
```

### Step

| Field                | Type          | Description                                                                                                                                                                                                                                                 |
| -------------------- | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                 | string (uuid) | Quote id.                                                                                                                                                                                                                                                   |
| `type`               | string        | `swap` (same chain) or `cross` (cross-chain).                                                                                                                                                                                                               |
| `tool`               | string        | Always `swapper`.                                                                                                                                                                                                                                           |
| `toolDetails`        | object        | `key` (`swapper`), `name` (`Swapper`), `logoURI`.                                                                                                                                                                                                           |
| `action`             | object        | What was asked: `fromChainId` and `toChainId` (Swapper chain ids, strings), `fromToken` and `toToken` ([Token](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#the-token-object)), `fromAmount`, `slippage`, `fromAddress`, `toAddress`. |
| `estimate`           | object        | What to expect — [below](#estimate).                                                                                                                                                                                                                        |
| `includedSteps`      | array         | Always empty.                                                                                                                                                                                                                                               |
| `integrator`         | string        | The integrator the quote was made for.                                                                                                                                                                                                                      |
| `transactionRequest` | object        | The transaction to send — [below](#transactionrequest).                                                                                                                                                                                                     |
| `expiresAt`          | integer       | Unix seconds after which the quote should be refreshed (advisory).                                                                                                                                                                                          |

### `estimate`

| Field                          | Type       | Description                                                                                                                                                                                                           |
| ------------------------------ | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `tool`                         | string     | Always `swapper`.                                                                                                                                                                                                     |
| `fromAmount` / `fromAmountUSD` | string     | Input amount (smallest unit) and its USD value.                                                                                                                                                                       |
| `toAmount`                     | string     | Expected output, after all included fees.                                                                                                                                                                             |
| `toAmountMin`                  | string     | Minimum output given `slippage`. Equals `toAmount` on routes that guarantee their output.                                                                                                                             |
| `toAmountUSD`                  | string     | USD value of `toAmount`.                                                                                                                                                                                              |
| `approvalAddress`              | string?    | EVM only. Spender to approve for `fromAmount` of an ERC-20 `fromToken`; for native tokens it's the transaction target. Absent on Solana, which needs no approval.                                                     |
| `executionDuration`            | integer    | Expected seconds from the source transaction to funds received. From the route when available, otherwise from Swapper's recent transfers on the same chain pair (`0` for a same-chain swap without a route estimate). |
| `feeCosts`                     | FeeCost\[] | `Swapper fee` (always), `Integrator fee` (when `fee` > 0), and costs charged by the route — [below](#feecost).                                                                                                        |
| `gasCosts`                     | GasCost\[] | Source-chain gas — [below](#gascost). Empty when it can't be estimated.                                                                                                                                               |
| `priceImpact`                  | string?    | Total value lost between input and output (fees and price impact) as a fraction of the input value; negative is a gain. Omitted when prices are unknown.                                                              |

### `FeeCost`

| Field         | Type    | Description                                                                                                                              |
| ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string  | One of `Swapper fee`, `Integrator fee`, `Bridge fee`, `Relayer fee`, `Protocol fee`, `Network fee`.                                      |
| `description` | string  | What the fee is for.                                                                                                                     |
| `token`       | Token   | Token the fee is charged in.                                                                                                             |
| `amount`      | string  | Amount, in the smallest unit of `token`.                                                                                                 |
| `amountUSD`   | string  | USD value.                                                                                                                               |
| `percentage`  | string  | Fraction of the input amount (`0.003` = 0.3%); `"0"` for a cost paid on top in another token (`included: false`).                        |
| `included`    | boolean | `true`: deducted from the swapped amount (already reflected in `toAmount`). `false`: paid on top, included in the transaction's `value`. |

Swapper doesn't disclose which liquidity sources or bridges serve a route, so route costs carry generic names.

### `GasCost`

| Field       | Type   | Description                                         |
| ----------- | ------ | --------------------------------------------------- |
| `type`      | string | Always `SEND`.                                      |
| `price`     | string | Gas price in wei; `"0"` when unknown (e.g. Solana). |
| `estimate`  | string | Expected gas units.                                 |
| `limit`     | string | Gas limit.                                          |
| `amount`    | string | Expected cost, in the native token's smallest unit. |
| `amountUSD` | string | USD value.                                          |
| `token`     | Token  | The native token.                                   |

### `transactionRequest`

| Field      | Type     | Description                                                                        |
| ---------- | -------- | ---------------------------------------------------------------------------------- |
| `from`     | string   | Sender (`fromAddress`).                                                            |
| `to`       | string?  | EVM only: the contract to call.                                                    |
| `chainId`  | integer? | EVM only: the numeric EVM chain id to send on (e.g. `8453`), as wallets expect it. |
| `data`     | string   | EVM calldata, or a base64-encoded Solana `VersionedTransaction`.                   |
| `value`    | string?  | EVM only: hex wei, e.g. `"0x0"`.                                                   |
| `gasLimit` | string?  | EVM only, hex; set when the route reports one.                                     |

On Solana, `transactionRequest` is just `{ from, data }`.

## Executing a quote

1. **Approve (ERC-20 sources only).** Make sure `estimate.approvalAddress` is approved to spend at least `fromAmount` of `action.fromToken`. Native tokens and Solana need no approval.
2. **Send the transaction.**
   * **EVM:** send `transactionRequest` (`to`, `data`, `value`, and `gasLimit` when present) from `fromAddress` on `transactionRequest.chainId` (the numeric EVM chain id).
   * **Solana:** `transactionRequest.data` is a base64-encoded `VersionedTransaction` — have the user sign and send it.
3. **Execute promptly.** Quotes are short-lived; re-quote after `expiresAt` rather than sending stale calldata.
4. **Track it** with [`GET /v1/status`](https://docs.swapper.finance/api-v1/endpoints/status.md) using the source transaction hash.

{% hint style="info" %}
The transaction is always signed by the **user's own wallet**. Swapper never holds a key that can move your users' funds.
{% endhint %}

## Errors

| Status | Code                 | When                                                                                                                                                                                                                                                                                                                                                                             |
| ------ | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `VALIDATION_ERROR`   | A parameter is missing or malformed, an address isn't valid for its chain's ecosystem, `toAddress` is missing across ecosystems, or `slippage` is out of range.                                                                                                                                                                                                                  |
| `400`  | `INVALID_INTEGRATOR` | `integrator` is missing (without a key), unknown, or not the API key's integrator.                                                                                                                                                                                                                                                                                               |
| `400`  | `INVALID_FEE`        | `fee` is malformed, above your maximum, or sent without an API key.                                                                                                                                                                                                                                                                                                              |
| `400`  | `UNSUPPORTED_CHAIN`  | `fromChain` or `toChain` isn't served by v1.                                                                                                                                                                                                                                                                                                                                     |
| `400`  | `UNSUPPORTED_TOKEN`  | `fromToken` or `toToken` isn't listed on its chain.                                                                                                                                                                                                                                                                                                                              |
| `401`  | `INVALID_API_KEY`    | An unknown or revoked API key was sent.                                                                                                                                                                                                                                                                                                                                          |
| `403`  | `ORIGIN_NOT_ALLOWED` | A keyless browser request from an origin your integrator doesn't allow.                                                                                                                                                                                                                                                                                                          |
| `404`  | `NO_ROUTE_FOUND`     | No route can serve the request — pair not supported, amount too low or too high, or not enough liquidity. Another amount or token may work. Also returned when the best route would lose more than half of the input's value (`priceImpact` above 0.5). A very small amount can still get a route whose costs exceed it: check `toAmount` and `feeCosts` before showing a quote. |
| `429`  | `RATE_LIMITED`       | See [Rate Limits](https://docs.swapper.finance/api-v1/rate-limits.md).                                                                                                                                                                                                                                                                                                           |
| `500`  | `INTERNAL_ERROR`     | Unexpected error. Safe to retry.                                                                                                                                                                                                                                                                                                                                                 |
| `502`  | `UPSTREAM_ERROR`     | A liquidity source or network is temporarily unavailable. Retry shortly.                                                                                                                                                                                                                                                                                                         |

For example, a missing `integrator` on a keyless request:

```json
{
  "error": {
    "code": "INVALID_INTEGRATOR",
    "message": "integrator is required: send your integrator id as integrator, or authenticate with an API key in the x-swapper-api-key header.",
    "requestId": "59b57df8-8b6a-4b9b-b6c8-001323b5ac53"
  }
}
```

Or an EVM `toAddress` on a quote to Solana:

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "toAddress 0x1111111111111111111111111111111111111111 is not a valid solana address for chain mainnet-beta",
    "requestId": "a3e1c0d2-7b4f-4e8a-9c61-2f0d8b5e7a14"
  }
}
```

See [Errors](https://docs.swapper.finance/api-v1/errors.md) for the envelope and all codes.
