Quote
POST /v1/quoteQuotes 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):
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.
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
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.
includedSteps
array
Always empty.
integrator
string
The integrator the quote was made for.
expiresAt
integer
Unix seconds after which the quote should be refreshed (advisory).
estimate
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.
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
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
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
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
Approve (ERC-20 sources only). Make sure
estimate.approvalAddressis approved to spend at leastfromAmountofaction.fromToken. Native tokens and Solana need no approval.Send the transaction.
EVM: send
transactionRequest(to,data,value, andgasLimitwhen present) fromfromAddressontransactionRequest.chainId(the numeric EVM chain id).Solana:
transactionRequest.datais a base64-encodedVersionedTransaction— have the user sign and send it.
Execute promptly. Quotes are short-lived; re-quote after
expiresAtrather than sending stale calldata.Track it with
GET /v1/statususing the source transaction hash.
Errors
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.
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