Skip to content
ChordChordChord Docs

Best route for a swap

GET
/quote
curl --request GET \
  --url 'https://api.getchord.xyz/v1/quote?chain=5042&inputMint=example&outputMint=example&amount=example&slippageBps=50&fast=0'

Quotes every venue on the chain in parallel, splits the order across venues when that improves the output, composes a two-hop route through the chain’s anchors when no direct pool wins, and returns the best.

Use it for: a price before a trade, a route card, an agent deciding whether to buy, a bot comparing venues.

Notes

  • Amounts are strings in the token’s smallest unit. On Arc the USDC predeploy has 6 decimals, native USDC 18 — send the predeploy address 0x3600…0000 (the zero address is an alias for it on 5042).
  • A quote is a live read of the venues and is good for about 30 seconds. Re-quote before you build if you waited longer.
  • fast=1 returns a single-hop answer in about 400 ms marked preliminary; run the full quote alongside and replace it.
  • only= pins one venue and bypasses the routing safety gates — it needs an API key.
  • An empty routePlan is a real answer (no route at this size); read noRouteReason.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “Query Parameters”
chain
integer
default: 143
Allowed values: 5042 4663 143 43114 8453 56 42161 1

Chain id: 5042 Arc · 4663 Robinhood Chain · 143 Monad · 43114 Avalanche C-Chain · 8453 Base · 56 BNB Chain · 42161 Arbitrum One · 1 Ethereum. Omitted = 143. Always pass it.

inputMint
required

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/

Token you sell. The zero address means the native unit (an alias for the USDC predeploy on Arc; ETH on Robinhood Chain).

outputMint
required

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/

Token you buy.

amount
required

Amount in the token’s smallest unit, as a decimal string. Never a float.

string
/^\d+$/

Input amount, smallest unit.

slippageBps
integer
default: 50 >= 1 <= 5000

Slippage tolerance in basis points; sets otherAmountThreshold.

fast
integer
Allowed values: 0 1

1 = progressive first frame (single-hop, ~400 ms, preliminary: true).

only
string
/^[a-z0-9_]+$/

Debug: restrict routing to one venue id. Requires X-API-Key.

Responses

Section titled “ Responses ”

200

Section titled “200”

The best route. routePlan empty + outputAmount “0” = no route.

Media typeapplication/json
object
inputMint

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
outputMint

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
inputAmount

Amount in the token’s smallest unit, as a decimal string. Never a float.

string
/^\d+$/
outputAmount

Amount in the token’s smallest unit, as a decimal string. Never a float.

string
/^\d+$/
otherAmountThreshold

Minimum output after fee and slippage — the number the transaction enforces.

string
/^\d+$/
slippageBps
integer
priceImpactPct

Percent, as a string, against the spot rate of the same route.

string
routePlan

Empty with outputAmount “0” = no route (an honest answer, never a fabricated price).

Array<object>

One leg of the route.

object
percent

Share of the input this leg carries.

integer
swapInfo
object
dex

Venue id (see Resources → Venue ids).

string
pool

Pool address, or the 32-byte pool id on Uniswap V4.

string
inputMint

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
outputMint

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
inputAmount

Amount in the token’s smallest unit, as a decimal string. Never a float.

string
/^\d+$/
outputAmount

Amount in the token’s smallest unit, as a decimal string. Never a float.

string
/^\d+$/
adapter

The router adapter that executes this leg — from the engine, never hardcode.

string
extraData

Adapter-specific calldata for the leg.

string
feeAmount

Amount in the token’s smallest unit, as a decimal string. Never a float.

string
/^\d+$/
feeMint

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
noRouteReason

Only when routePlan is empty: INSUFFICIENT_LIQUIDITY (try a smaller amount) or NO_POOLS.

string
gasEstimate

Gas units, from the venue quoter or the RPC.

string
gasCostUSD
string
blockNumber
integer
timeTaken

Engine seconds.

number
feeBps

Protocol fee on the output token, per token on-chain (FeeCollector.feeBpsFor): 5 bps by default on every chain, 0 on the stablecoins and majors a chain exempts (USDC / EURC on Arc, WETH / USDG and stocks on Robinhood Chain), capped at 100.

integer
feeAmount

Amount in the token’s smallest unit, as a decimal string. Never a float.

string
/^\d+$/
feeMint

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
feeTier

major · stable · standard · meme · new.

string
preliminary

Present only on fast=1 answers: single-hop, ~400 ms, replace it with the full quote.

boolean
Example
{
  "inputMint": "0x3600000000000000000000000000000000000000",
  "outputMint": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
  "inputAmount": "5000000",
  "outputAmount": "465",
  "otherAmountThreshold": "460",
  "slippageBps": 100,
  "priceImpactPct": "92.51",
  "routePlan": [
    {
      "percent": 100,
      "swapInfo": {
        "dex": "uniswap_v4",
        "pool": "0xdd9da42901118c475e6efb78117100e611c675e2c53bc801c4d2bfdd504b2e8d",
        "inputMint": "0x3600000000000000000000000000000000000000",
        "outputMint": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
        "inputAmount": "5000000",
        "outputAmount": "465",
        "adapter": "0xd1d86d370f40471B79D9938B27F6ea040EbD6888",
        "extraData": "0x000000000000000000000000171a4217b86a807a64eb94757db6849fb4bdbaa00000000000000000000000003600000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000017700000000000000000000000000000000000000000000000000000000000000040000000000000000000000000000000000000000000000000000000000000000"
      }
    }
  ],
  "gasEstimate": "318189",
  "gasCostUSD": "0",
  "blockNumber": 21808240,
  "timeTaken": 0.643,
  "feeBps": 25,
  "feeAmount": "1",
  "feeMint": "0x171a4217b86a807a64eb94757db6849fb4bdbaa0",
  "feeTier": "meme"
}

400

Section titled “400”

Invalid parameters — error names the check that failed (INVALID_PARAMS, BAD_ADDRESS, BAD_LIMIT, BAD_HOURS, …).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

429

Section titled “429”

Over the per-minute limit (RATE_LIMIT_EXCEEDED). Read X-RateLimit-Reset and back off.

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

502

Section titled “502”

The routing engine or an upstream did not answer (ENGINE_ERROR, ROUTE_ERROR).

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}

503

Section titled “503”

The lane behind this endpoint is not ready or not enabled here (NOT_READY, CHAIN_NOT_ENABLED, NOT_ENABLED, *_UNAVAILABLE). Retry later; do not treat it as an empty answer.

Media typeapplication/json

Every non-2xx body.

object
error
required

Stable machine code, e.g. INVALID_PARAMS, NOT_READY, RATE_LIMIT_EXCEEDED.

string
message

For humans.

string
statusCode

HTTP status, when included.

integer
Example
{
  "error": "INVALID_PARAMS",
  "message": "amount must be an integer string in the token's smallest unit"
}