Cross-chain swap plan

POST

/xswap/plan

const url = 'https://api.getchord.xyz/v1/xswap/plan';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"user":"0xb145400da27a2497d9fc2cd5621f2bfd37617af4","chainIn":5042,"chainOut":143,"tokenIn":"0x3600000000000000000000000000000000000000","tokenOut":"0x350035555e10d9afaf1566aaebfced5ba6c27777","amount":"1000000000","slippageBps":100}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

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

Quotes a token on one chain into a token on another two ways at once — composed (Chord’s router on the origin → USDC/USDG rail → Chord’s router on the destination) and direct (Relay end to end) — and names the one that lands more. Long-tail tokens on Arc / Monad / Robinhood only route on the composed path. Fees come back as three lines (protocol · bridge · network) and gas says who pays on each side. MIN_SIZE below 10 USD of the bridged stable.

Request Body^required

application/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

Example

{
  "user": "0xb145400da27a2497d9fc2cd5621f2bfd37617af4",
  "chainIn": 5042,
  "chainOut": 143,
  "tokenIn": "0x3600000000000000000000000000000000000000",
  "tokenOut": "0x350035555e10d9afaf1566aaebfced5ba6c27777",
  "amount": "1000000000",
  "slippageBps": 100
}

Responses

200

application/json

object

best

string

Allowed values: composed direct

composed

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
object

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

direct

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
object

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

errors

Per-path failure { code, message } when a path could not be quoted.

object

key

additional properties

any

Example

{
  "best": "composed",
  "composed": {
    "legs": [
      {
        "kind": "swap"
      }
    ],
    "rail": "relay",
    "fees": {
      "network": {
        "mode": "user"
      }
    }
  },
  "direct": {
    "legs": [
      {
        "kind": "swap"
      }
    ],
    "rail": "relay",
    "fees": {
      "network": {
        "mode": "user"
      }
    }
  }
}

400

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

application/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

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

application/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

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

application/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

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

application/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

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.

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

Cross-chain swap plan

Request Bodyrequired

Example

Responses

200

Example

400

Example

404

Example

429

Example

502

Example

503

Example

Request Body^required