Skip to content
ChordChordChord Docs

Build an unsigned swap transaction

POST
/swap
curl --request POST \
  --url https://api.getchord.xyz/v1/swap \
  --header 'Content-Type: application/json' \
  --data '{ "quoteResponse": { "…": "the /v1/quote body" }, "userPublicKey": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "chain": 5042 }'

Turns a quote into a transaction against the Chord router. You sign it and broadcast it; Chord never sees a key and never holds funds.

Notes

  • Send the /quote body back unmodified. chain must match the quote.
  • For an ERC-20 input, approve the router (transaction.to) for at least inputAmount first — or run /swap/simulate and let it tell you.
  • slippageBps is a consistency check only: the signed minimum output is the quote’s otherAmountThreshold. A different value is refused with SLIPPAGE_MISMATCH — re-quote at the slippage you want.
  • On Arc the native sentinel aliases to the USDC predeploy: a “native” input is pulled by transferFrom, a “native” output is delivered as the predeploy, and value is always 0.
  • batch: "7702" is Monad-only (EIP-7702 one-signature approve+swap); it is ignored on every other chain.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
quoteResponse
required
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
userPublicKey
required

Wallet that signs and receives the output.

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

Must match the quote.

integer
default: 143
Allowed values: 5042 4663 143 43114 8453 56 42161 1
slippageBps

Optional consistency check — same value the quote was requested with.

integer
>= 1 <= 5000
feeAccount

Referrer credited with the referral share of the protocol fee.

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

Wrap / unwrap the native unit around the swap where the chain has a wrapped native (not Arc).

boolean
default: true
usePermit2
boolean
batch
string
Allowed values: 7702
Example
{
  "quoteResponse": {
    "…": "the /v1/quote body"
  },
  "userPublicKey": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4",
  "chain": 5042
}

Responses

Section titled “ Responses ”

200

Section titled “200”

Sign transaction with any wallet library and submit it to the chain in chainId.

Media typeapplication/json
object
transaction

Unsigned transaction against the router.

object
to

EVM address, hex, case-insensitive.

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

Calldata.

string
value

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

string
/^\d+$/
gasLimit
string
chainId
integer
lastValidBlockHeight

Block after which the quote should be considered stale.

integer
batch7702

Monad only — the one-signature approve+swap plan.

object
key
additional properties
any
Example
{
  "transaction": {
    "to": "0x1b1fee89a381e595fe6536b99ba91f3e16e9601a",
    "data": "0xdc72a437…",
    "value": "0",
    "gasLimit": "1500000",
    "chainId": 5042
  },
  "lastValidBlockHeight": 21808340
}

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"
}