> 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/overview.md).

# Overview

**Swapper API v1** is the versioned API for integrators who build their own deposit or swap experience: list the chains and tokens Swapper supports, get a quote with a ready-to-sign transaction, and track the transfer until it lands. It runs on the same routing engine as the [widget](https://docs.swapper.finance/widget-integration/iframe-sdk.md), with API keys, published rate limits, stable error codes, and [integrator fees](https://docs.swapper.finance/api-v1/integrator-fees.md).

{% hint style="info" %}
**Using TypeScript or JavaScript?** `@swapper-finance/deposit-sdk` includes `SwapperApiClient`, a typed client for v1, with retries, rate-limit headers and status polling built in — see [TypeScript SDK](https://docs.swapper.finance/api-v1/sdk.md).
{% endhint %}

## Base URL

```
https://swapper.finance/api/v1
```

All paths on these pages are relative to this base (e.g. `POST https://swapper.finance/api/v1/quote`). v1 is **production (mainnet) only** — there is no testnet environment for the API.

`GET https://swapper.finance/api/v1` answers `{"version":"v1"}`, which makes a handy connectivity check.

## Two ways to call it

|                                                                                  | Free tier (no key)                  | With an API key                                                 |
| -------------------------------------------------------------------------------- | ----------------------------------- | --------------------------------------------------------------- |
| How you're identified                                                            | `integrator`: your `integratorId`   | `x-swapper-api-key` header — the key identifies your integrator |
| Call it from                                                                     | Your servers or the browser         | **Your servers only**                                           |
| Rate limits (per minute)                                                         | 50 quote / 300 other, per client IP | 600 quote / 1,200 other, per integrator                         |
| [Integrator fee](https://docs.swapper.finance/api-v1/integrator-fees.md) (`fee`) | Not available                       | Up to 3%                                                        |

See [Authentication](https://docs.swapper.finance/api-v1/authentication.md) and [Rate Limits](https://docs.swapper.finance/api-v1/rate-limits.md) for the details. API keys are created in the [Integrator Dashboard](https://docs.swapper.finance/integrator-dashboard/overview.md).

## Quick start

The examples quote **10 USDC on Base** (`8453`) into **ETH on Arbitrum** (`42161`). Amounts are integer strings in the token's smallest unit, so 10 USDC (6 decimals) is `10000000`.

### 1. Get a quote

```bash
curl -X POST "https://swapper.finance/api/v1/quote" \
  -H "Content-Type: application/json" \
  -d '{
    "integrator": "YOUR_INTEGRATOR_ID",
    "fromChain": 8453,
    "toChain": 42161,
    "fromToken": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "toToken": "0x0000000000000000000000000000000000000000",
    "fromAmount": "10000000",
    "fromAddress": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e"
  }'
```

With an API key, send it in the `x-swapper-api-key` header instead of `integrator`, from your server — that's also what lets you add your own [`fee`](https://docs.swapper.finance/api-v1/integrator-fees.md). `toAddress` defaults to `fromAddress`; `slippage` defaults to `0.005` (0.5%). All fields: [Quote](https://docs.swapper.finance/api-v1/endpoints/quote.md).

### 2. Sign and send

The quote is a single **step**: the route, its estimate, and the transaction to send. Abridged:

```json
{
  "id": "6f1c2a9e-4b7d-4c1e-9f0a-3d2b8e5c7a10",
  "type": "cross",
  "action": {
    "fromChainId": "8453",
    "toChainId": "42161",
    "fromAmount": "10000000",
    "slippage": 0.005
  },
  "estimate": {
    "toAmount": "2629870000000000",
    "toAmountMin": "2616720000000000",
    "approvalAddress": "0x5f2c7a1e9b3d4c6a8e0f1b2d3c4e5f6a7b8c9d0e",
    "executionDuration": 45
  },
  "transactionRequest": {
    "from": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e",
    "to": "0x5f2c7a1e9b3d4c6a8e0f1b2d3c4e5f6a7b8c9d0e",
    "chainId": 8453,
    "data": "0x…",
    "value": "0x0"
  },
  "expiresAt": 1791043260
}
```

1. **ERC-20 source:** make sure `estimate.approvalAddress` is approved to spend at least `fromAmount` of the source token; send an `approve` first if not. Native-token sources need no approval.
2. **Send `transactionRequest`** from `fromAddress` — the user signs it in their own wallet. On Solana, `data` is a base64-encoded `VersionedTransaction` to sign and send.
3. **Re-quote after `expiresAt`** (unix seconds). Quotes are short-lived; don't send stale calldata.

### 3. Track it

Poll the status with the source-chain transaction hash (and the source chain) until it settles:

```bash
curl -G "https://swapper.finance/api/v1/status" \
  --data-urlencode "txHash=0xa6b7…3456" \
  --data-urlencode "fromChain=8453"
```

`status` is `PENDING` while the transfer is in flight and ends as `DONE` or `FAILED`; right after broadcasting it can briefly be `NOT_FOUND`. See [Status](https://docs.swapper.finance/api-v1/endpoints/status.md).

A transfer is only recorded once something tracks it, so always poll `/v1/status`: that's what sends the `transaction.completed` [webhook](https://docs.swapper.finance/tracking-deposits/webhooks.md) and attributes your [integrator fee](https://docs.swapper.finance/api-v1/integrator-fees.md#getting-paid) to the transfer.

## Conventions

* **Requests.** `GET` endpoints take flat query parameters; lists are comma-separated (`chains=8453,42161`) or repeated (`chains=8453&chains=42161`). `POST` endpoints take a JSON body (`Content-Type: application/json`).
* **Amounts** are integer **strings** in the token's smallest unit (wei, lamports, `1000000` = 1 USDC). **USD values** are decimal strings.
* **`slippage` and `fee` are decimal fractions:** `0.005` = 0.5%.
* **Chains** are identified by Swapper's chain id — a string such as `"8453"`, `"42161"` or `"mainnet-beta"` (Solana) — or by chain key (`base`, `arbitrum`, `solana`), as listed by [`GET /v1/chains`](https://docs.swapper.finance/api-v1/endpoints/chains-and-tokens.md#list-chains). These are the same ids the deposit widget uses. Requests take either; in a JSON body, EVM ids can also be numbers (`8453`). Responses always carry the id, as a string.
* **Native tokens** are the zero address on EVM (`0x0000000000000000000000000000000000000000`; `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` is accepted too) and `So11111111111111111111111111111111111111111` on Solana (the System Program `11111111111111111111111111111111` is accepted too).
* **Tokens** can be given by address or by symbol (`USDC`); only tokens listed by `GET /v1/tokens` can be quoted.
* **EVM addresses** in responses are usually lowercase; compare them case-insensitively.
* **Every response** carries an `X-Request-Id` header. Errors use one envelope — `{ "error": { "code", "message", "requestId" } }` — see [Errors](https://docs.swapper.finance/api-v1/errors.md).
* **New fields can appear at any time.** Ignore fields you don't recognize; see [Versioning](https://docs.swapper.finance/api-v1/versioning.md).

## How routes are reported

* **One step, `tool: "swapper"`.** Swapper picks the best route among several liquidity sources and bridges and returns it as a single step: `tool` is always `swapper`, `includedSteps` is always empty, and fee entries use generic names (e.g. "Bridge fee", "Network fee").
* **Quotes expire.** Every quote carries `expiresAt`; re-quote after it. The estimate also includes `priceImpact`, the total value lost between input and output.
* **No route is a `404`** with the code `NO_ROUTE_FOUND` — branch on `code`, not on the status alone.
* **Ecosystems:** v1 routes between EVM chains and Solana; each chain's `ecosystem` (`evm` or `solana`) is listed by `GET /v1/chains`.

{% hint style="info" %}
v1 never moves funds on its own. A quote returns a transaction for the **user's wallet** to sign and broadcast; Swapper never holds a key that can sign for your users.
{% endhint %}

All endpoints are listed under [Endpoints](https://docs.swapper.finance/api-v1/endpoints.md).
