Skip to main content
GET
Get a partner-ready executable exact-input quote
This is the recommended endpoint for new wallet, router, and meta-aggregator integrations. It returns an exact-input executable quote and does not broadcast a transaction.
payer supplies the input and sends the returned transaction. recipient receives the output and defaults to payer. A successful response can contain balance, allowance, or native gas entries in issues. Resolve them before broadcasting. A validation status of UNKNOWN means AKKA could not complete that RPC check; validate it independently. Use simulation.status, not HTTP status alone, to decide whether your own simulation is required. A payer that does not yet hold the sell amount or the router approval is still simulated: the estimate grants exactly what is missing through eth_estimateGas state overrides and lists it in simulation.stateOverrides (balance, allowance), while issues keeps reporting the shortfall. simulation.gasLimit is the transaction gas limit to send: on SUCCESS it is the estimate +20%; on INCOMPLETE and SKIPPED_METRIC_STATE it is a static route plan, so never send less and simulate independently on INCOMPLETE. By default simulation.gas, tx.gas and the root gas are that same limit (simulation.gasUsedMethod is limit). simulation.estimatedGasUsed is the expected consumption to use for cost display. The payer gas checks (validation.gas, INSUFFICIENT_GAS_BALANCE, and the native-input balance) budget simulation.gasLimit, and encodedTx carries it. Refresh after expiresAt, any approval transaction, user delay, failed simulation, or nonce replacement. Executable calldata is single-use and must not be cached or retried after broadcast. Inspect tx.type: send only gasPrice for legacy, or only maxFeePerGas and maxPriorityFeePerGas for eip1559. Preserve tx.to, tx.data, and tx.value exactly. Set includeRoutes=true for the parallel route list, includeGraph=true for the flat on-chain hop list, or includeCompare=true for same-moment single-pool comparison quotes. All three views come from the same pathfinder invocation that produced dstAmount and tx.data — one call, one number, one route. includeTokensInfo and includeGas default to true on this endpoint. gasPrice and gasLimit override the RPC lookups. A gasLimit becomes the limit (on a route with a Metric leg the limit is never below the route floor) and skips the RPC estimate, so simulation.status is INCOMPLETE (SKIPPED_METRIC_STATE with a Metric leg). There is no exactQuote parameter: an executable quote is always exact.
Expected-gas reporting (a per-key option agreed with AKKA in writing). For a key with this option, gas, tx.gas, simulation.gas and estimatedGasUsed carry the expected receipt gas: what receipt.gasUsed shows, after the gas refund and with no buffer, for cost display and route ranking. It is not a gas limit: a transaction sent with it runs out of gas. Only simulation.gasLimit is the limit to send. simulation.gasUsedMethod says how the expected value was made:
  • simulateV1: an eth_simulateV1 of the exact transaction (the payer state overrides of the estimate), accepted when the call succeeds and uses more than 21,000 gas and at most the raw estimate. It is the receipt gas at the state of the quote block. Replays of real swaps at their parent block matched the receipt within 0.01% on 34 of 40 Ethereum swaps and exactly on 14 of 18 HyperEVM swaps, and came out +0.004% to +1.8% on Arbitrum and up to +532 gas on Robinhood (the L1 part included). Pool state that changes before your transaction lands moves the receipt either way: the Ethereum replays moved by -3.8% to +10.7% where earlier transactions of the same block touched the pools.
  • refundRatio: the raw eth_estimateGas times the chain’s receipt/estimate ratio (0.87 on Ethereum; 0.84 on Arbitrum and HyperEVM; 0.855 on Robinhood; 0.80 on XDC), when no simulation is available. Each ratio is set above the highest one observed on the chain, so this value errs high (typically 5–10% over the receipt). The estimate is the gas before the refund, 1.15–1.30x the receipt.
  • estimate: the raw eth_estimateGas result, on a chain without a measured ratio.
  • routeModel: the gas model of the primary route, when no estimate ran.
  • limit: no expected value exists; the limit stands in.
More values may be added. An unknown value is opaque: it says how gas was made and never changes what gas means for your key. Sending simulation.gasLimit as the gas limit is correct in both modes.
Keep the partner API key on a backend. Browser and mobile clients should call an authenticated proxy owned by the integrator.

Authorizations

apikey
string
header
default:basic-test-key
required

API key. basic-test-key is a shared, rate-limited evaluation credential; use a dedicated key in production.

Path Parameters

chainId
integer
required
Example:

999

Query Parameters

src
string
required

Exact-input source token address

dst
string
required

Destination token address

amount
string
required

Sell amount in the token smallest unit

payer
string
required

Transaction sender and token payer

recipient
string

Output recipient; defaults to payer

slippage
object
required

Slippage percentage

includeTokensInfo
boolean
default:true

Include srcToken and dstToken info in response

includeGas
boolean
default:true

Include the root gas in response, equal to tx.gas and simulation.gas (the gas limit by default; the expected consumption with expected-gas reporting)

includeRoutes
boolean
default:false

Include the details of the routes in response. Sourced from the same pathfinder invocation that produced dstAmount and the calldata.

includeGraph
boolean
default:false

Include the flat on-chain DAG hop list (one entry per pool) of the served route. Same semantics as /quote includeGraph.

includeCompare
boolean
default:false

Include same-moment top single-pool comparison quotes harvested from this quote's own floor-guard pass. Same semantics as /quote includeCompare.

gasPrice
string

Network price per gas in wei (overrides the RPC lookup)

gasLimit
string

Gas limit for the transaction. Any value skips the RPC estimate, so simulation.status is INCOMPLETE (SKIPPED_METRIC_STATE on a route with a Metric leg) and simulation.method is routeGasFloor. It becomes simulation.gasLimit (and by default gas, tx.gas and simulation.gas), except on a route with a Metric leg, where the limit is never below the route floor. With expected-gas reporting gas, tx.gas and simulation.gas stay the expected consumption: the gas model of the primary route, not an RPC estimate.

Response

200 - application/json
dstAmount
string
required

Expected output amount in wei (destination amount)

Example:

"12723902882990271"

tx
object
required

Transaction data to execute the swap. Send to, data and value unchanged, with simulation.gasLimit as the gas limit (by default tx.gas holds the same value; with expected-gas reporting tx.gas is the expected receipt gas).

encodedTx
string
required

ABI-encoded transaction tuple (from, to, data, value, gasPrice, gas) as a hex string. Its gas is simulation.gasLimit, the sendable limit, in both modes.

chainId
number
required
sellToken
string
required
buyToken
string
required
sellAmount
string
required
buyAmount
string
required
payer
string
required
recipient
string
required
issues
object[]
required
validation
object
required
simulation
object
required
validForSeconds
number
required
validitySource
enum<string>
required
Available options:
ADVISORY,
ROUTE_DEADLINE
partnerId
string
required
srcToken
object

Source token information

dstToken
object

Destination token information

quoteId
string

Unique identifier for this executable quote

blockNumber
string

Block used for quote metadata

generatedAt
string

ISO-8601 quote generation time

expiresAt
string

Advisory ISO-8601 refresh deadline

minAmountOut
string

Minimum output encoded in the transaction

allowanceTarget
object

ERC-20 approval target; null for native input

simulationIncomplete
boolean

True when RPC simulation/gas estimation did not complete

simulationStatus
enum<string>
Available options:
SUCCESS,
INCOMPLETE,
SKIPPED_METRIC_STATE
simulationStateOverrides
enum<string>[]

Payer state a SUCCESS estimate assumed through eth_estimateGas state overrides (missing sell-token balance and/or router allowance). Omitted when the estimate ran on the real payer state.

Available options:
balance,
allowance
gas
string

Gas (decimal-string uint256), identical to simulation.gas and tx.gas; omitted with includeGas=false. By default the transaction gas limit; with expected-gas reporting the expected receipt gas (see simulation.gasUsedMethod). The limit to send is simulation.gasLimit.

Example:

"420000"

estimatedGasUsed
string

Expected gas consumption (decimal-string uint256), the same value as simulation.estimatedGasUsed. Not a limit, and independent of a caller-supplied gasLimit. By default it is the /swap/v1 value. With expected-gas reporting it also equals simulation.gas, tx.gas and the root gas: the expected receipt gas (after the refund), so it can be below the /swap/v1 estimatedGasUsed of the same route (the raw estimate, or the route plan without an estimate).

Example:

"350000"

quotedAtBlock
string
routes
object[]

Routes of THIS quote (?includeRoutes=true) — same pathfinder invocation that produced dstAmount and the calldata.

graph
object[]

Flat on-chain DAG hop list of the served route (?includeGraph=true). Same semantics as /quote includeGraph.

compare
object

Same-moment top single-pool comparison quotes (?includeCompare=true), harvested from this quote's floor-guard pass. Same shape as /quote includeCompare.