// Developers

API Reference

The RouterX REST API exposes same-chain quoting and swap calldata over HTTPS. Cross-chain quotes are built locally by the TypeScript SDK (rx.cross.quote); the Cross API stores transfer history.

Base URL#

text

https://api.routerx.exchange

Paths are under /v1. Amounts are decimal strings in the token's smallest unit. Responses wrap payloads as { "code": 0, "data": … }.

Public meta routes need no key: /v1/:chain/dexList, tokenList, gasPrice, and tokenInfo, plus /healthz. Quote and swap accept an optional x-api-key header (or ?apiKey=) when keys are configured on the server.

Prefer the SDK for Cross quotes

Same-chain /quote and /swap are HTTP. Cross quotes run in @routerx.exchange/sdk via rx.cross.quote (on-chain RXRouter + Iris fees) — the Cross HTTP POST /v1/quote is disabled.

GET /:chain/quote#

GET/v1/:chain/quote

Returns the best gas-adjusted route for a single swap. :chain accepts a chain ID (8453) or code (base).

bash

curl "https://api.routerx.exchange/v1/8453/quote?tokenIn=0x4200000000000000000000000000000000000006&tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amountIn=1000000000000000000"

Query parameters

Parameter	Type	Description
`tokenIn`	address	Input token. Required. Native uses 0xEeee…EEeE.
`tokenOut`	address	Output token. Required.
`amountIn`	string	Input amount in base units. Required.
`maxSteps`	number	Max hops. Optional; defaults to the chain config.
`gasPrice`	string	Gas price in wei for route scoring. Optional.

Response

200 OK

{
  "code": 0,
  "data": {
    "chainId": 8453,
    "tokenIn": "0x4200000000000000000000000000000000000006",
    "tokenOut": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amountIn": "1000000000000000000",
    "amountOut": "2431382901",
    "offer": {
      "amounts": ["1000000000000000000", "2431382901"],
      "adapters": [{ "address": "0x6A7c…", "name": "PancakeV3Adapter" }],
      "path": ["0x4200…", "0x8335…"],
      "gasEstimate": "0",
      "extras": ["0x"]
    },
    "router": "0x1abe089620a6f3E3Ff802f2165AB8dbC10cd5CE8",
    "cached": false,
    "quoteMode": "full"
  }
}

GET /:chain/swap#

GET/v1/:chain/swap

Same as quote, plus executable transaction fields. Encodes swap / swapFromAVAX / swapToAVAX calldata on the CREATE2 router.

bash

curl "https://api.routerx.exchange/v1/8453/swap?tokenIn=0x4200000000000000000000000000000000000006&tokenOut=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amountIn=1000000000000000000&to=0xYourRecipient"

Extra parameters

Parameter	Type	Description
`to`	address	Recipient. Required.
`slippage`	number	Slippage percent. Default 0.5.
`fee`	number	Fee in bps. Optional.

Response includes minAmountOut and tx: { to, data, value }. Native tokenIn sets value = amountIn; ERC-20 input requires an allowance to the router first.

GET /:chain/tokenList#

GET/v1/:chain/tokenList

Official token list for a chain (address, symbol, name, decimals, icon). No API key. Related: /v1/:chain/dexList, /v1/:chain/gasPrice, /v1/:chain/tokenInfo?tokenAddress=, and /v1/chains.

bash

curl "https://api.routerx.exchange/v1/8453/tokenList"

GET /healthz#

GET/healthz

Health check plus per-chain RPC breaker and pair-index status. No API key.

200 OK

{
  "status": "ok",
  "timestamp": 1789616958073,
  "breakers": {
    "8453": { "name": "rpc:base", "state": "closed", "openUntilMs": 0 }
  },
  "pairIndex": { "4663": { "enabled": true, "pairs": 58 } }
}

Cross API#

text

https://cross-api.routerx.exchange

routerx-cross stores Cross transfer history. Quotes are not served over HTTP — use rx.cross.quote in @routerx.exchange/sdk (local RXRouter legs + Circle Iris fees). Override the history host with crossApiUrl.

CCTP ∩ swap Composer sources

Ethereum, Optimism, Unichain, Polygon, Base, Arbitrum, Avalanche, Monad, World Chain, HyperEVM, and Arc. BSC, Robinhood, Katana, and Plasma are swap-only and are not Cross sources. Arc Wave A is ERC-20 only.

POST /v1/quote

POST/v1/quote

Disabled (HTTP 410). Kept as a stub for possible partner access later. Example SDK request shape for rx.cross.quote:

CrossQuoteRequest

{
  "srcChainId": 8453,
  "dstChainId": 42161,
  "tokenIn": "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE",
  "tokenOut": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
  "amountIn": "1000000000000000000",
  "slippageBps": 50
}

Transfers

Method	Path	Description
POST	`/v1/transfers`	Create a transfer record
GET	`/v1/transfers?account=`	List by account
GET	`/v1/transfers/:id`	Get one transfer
PATCH	`/v1/transfers/:id`	Patch status / hashes
PATCH	`/v1/transfers/by-burn`	Patch by burn tx
POST	`/v1/transfers/:id/refresh`	One-shot Iris fill-in

Errors#

Failed requests return an HTTP status with { "code": <status>, "message": "…" }.

Status	Meaning
400	Missing or malformed parameters (e.g. invalid amountIn).
401	Invalid or missing API key when keys are required.
404	Unsupported chain or no route for the pair/size.
500	Internal error — retry or check /healthz breakers.

error body

{ "code": 400, "message": "invalid amountIn: abc（需为正整数字符串，含 decimals）" }

API Reference

Base URL#

Authentication#

GET /:chain/quote#

Query parameters

Response

GET /:chain/swap#

Extra parameters

GET /:chain/tokenList#

GET /healthz#

Cross API#

POST /v1/quote

Transfers

Errors#