For the complete documentation index, see llms.txt. Markdown versions of documentation pages are available by appending .md to page URLs.
Skip to content

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.

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 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. Quotes count against the quote rate limit.

Example

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

Response

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), fromAmount, slippage, fromAddress, toAddress.

estimate

object

What to expect — below.

includedSteps

array

Always empty.

integrator

string

The integrator the quote was made for.

transactionRequest

object

The transaction to send — below.

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.

gasCosts

GasCost[]

Source-chain gas — below. 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 using the source transaction hash.

The transaction is always signed by the user's own wallet. Swapper never holds a key that can move your users' funds.

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

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:

Or an EVM toAddress on a quote to Solana:

See Errors for the envelope and all codes.

Last updated