Skip to content
ChordChordChord Docs

Register a cross-chain order

POST
/xswap/order
curl --request POST \
  --url https://api.getchord.xyz/v1/xswap/order \
  --header 'Content-Type: application/json' \
  --data '{ "user": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4", "chainIn": 5042, "chainOut": 143, "tokenIn": "0x3600000000000000000000000000000000000000", "tokenOut": "0x350035555e10d9afaf1566aaebfced5ba6c27777", "amount": "1000000000", "slippageBps": 100 }'

Quotes and records the order the wallet is about to sign so it can be resumed after a refresh: the server tracks the bridge (Relay status or Circle attestation), mints CCTP transfers on Arc, and re-quotes the final leg at the amount that actually arrived. Poll GET /xswap/order?id=. path: "direct" registers the Relay end-to-end candidate instead.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
user
required

EVM address, hex, case-insensitive.

string
/^0x[a-fA-F0-9]{40}$/
chainIn
required
integer
Allowed values: 143 4663 5042
chainOut
required
integer
Allowed values: 143 4663 5042
tokenIn
required

EVM address, hex, case-insensitive.

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

EVM address, hex, case-insensitive.

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

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

string
/^\d+$/
slippageBps
integer
default: 100 >= 10 <= 500
recipient

EVM address, hex, case-insensitive.

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

Force a rail; auto applies the corridor rules (Robinhood → Relay; Monad ↔ Arc → CCTP when the mint relayer is funded; else Relay).

string
default: auto
Allowed values: auto relay cctp
path
string
default: composed
Allowed values: composed direct
Example
{
  "user": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4",
  "chainIn": 5042,
  "chainOut": 143,
  "tokenIn": "0x3600000000000000000000000000000000000000",
  "tokenOut": "0x350035555e10d9afaf1566aaebfced5ba6c27777",
  "amount": "1000000000",
  "slippageBps": 100
}

Responses

Section titled “ Responses ”

200

Section titled “200”
Media typeapplication/json
object
order

{ id, state, rail, chainIn, chainOut, tokenIn, tokenOut, amountIn, quotedOut, requestId, originTxHash?, destTxHash?, bridgedAmount?, destQuote?, claim?, note? } — states: pending_origin · bridging · pending_dest · done · stuck_dest · failed_origin.

object
key
additional properties
any
quote
object
chainIn
integer
chainOut
integer
tokenIn

EVM address, hex, case-insensitive.

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

EVM address, hex, case-insensitive.

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

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

string
/^\d+$/
amountOut

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

string
/^\d+$/
legs
Array
One of:
object
kind
string
Allowed value: swap
chainId
integer
tokenIn

EVM address, hex, case-insensitive.

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

EVM address, hex, case-insensitive.

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

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

string
/^\d+$/
amountOut

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

string
/^\d+$/
priceImpactPct
number
feeBps

Our tier fee on this leg’s output.

integer
dexIds
Array<string>
timeEstimateSec
number
rail
string
Allowed values: relay cctp
railReason

Why this rail.

string
fees
object
protocol

Our on-chain tier fee per swap leg.

object
originBps
integer
destBps
integer
usd
number
bridge

The bridge’s own cut.

object
rail
string
usd
number
bps
number
appFeeBps

App fee added on Relay.

integer
network

Gas we front on the destination.

object
usd

Flat per relayer-paid transaction.

number
covered

True = we eat it (Arc mint).

boolean
mode
string
Allowed values: user usdc-gas gasless solver none
totalUsd
number
gas

Who pays gas on each side.

object
origin
string
dest
string
minAnchorUnits

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

string
/^\d+$/
bridge

Rail-shaped: { rail, requestId, checkEndpoint, steps[], fees, details } — sign steps in order on the origin chain (an approval item may be skipped when the allowance covers it).

object
key
additional properties
any
requoteToleranceBps
integer
Example
{
  "quote": {
    "legs": [
      {
        "kind": "swap"
      }
    ],
    "rail": "relay",
    "fees": {
      "network": {
        "mode": "user"
      }
    }
  }
}

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

404

Section titled “404”

Nothing at this identity (NOT_FOUND, UNKNOWN_TOKEN, NO_ROUTE).

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