API Reference

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, trustedTokens, tokenList, gasPrice, tokenInfo, and rpcs, plus /healthz. Quote, quotePlan, and swap (GET and POST) take an x-api-key header when keys are configured on the server. The key is header-only; ?apiKey= is no longer accepted.

GET/v1/:chain/quote

Returns the best gas-adjusted route for a single swap. Reads go to RXQuoter (0x27fe…a666); data.router is the swap proxy. :chain accepts a chain ID (8453) or code (base).

The server builds candidates from its pair index (direct routes plus two-leg routes through the chain's hop tokens), ranks them by per-adapter USD reserve, and fans them out as Multicall3 batches of queryExactPath. A hit sets quoteMode to "narrow". If no candidate returns an amount, the response is 404 (no route); the server does not fall back to a full RXQuoter.query search. For a token the index has not seen, the server first waits up to about 1.5 seconds to pull its pools from GeckoTerminal. To run the same calls on your own RPC, use quotePlan below.

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

"legs": [
  { "split": 7000, "amountIn": "140000000000000000000", "amountOut": "334824958185", "gasEstimate": "…",
    "hops": [{ "adapter": "0x…", "name": "UniswapV3", "tokenOut": "0x…", "extra": "0x…" }] },
  { "split": 3000, "amountIn": "60000000000000000000", "amountOut": "…", "gasEstimate": "…", "hops": [ … ] }
]

{
  "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": "narrow",
    "rpcSource": "primary"
  }
}

GET/v1/:chain/quotePlan

Same query parameters as /quote. The server reads the in-memory pair index and returns calldata. It does not quote. You eth_call the plan on your own RPC, then POST the winning offer to /swap.

• eth_call each entry in calls (to is Multicall3). Decode the result as the return value of aggregate3. Row i matches candidateIds[i].
• For each row with success: true, decode returnData as the return value of queryExactPath and keep the offer whose last amounts entry is largest.
• If calls is empty, or every candidate fails or returns 0, there is no route. Do not fall back to a full search.
• POST the chosen offer (amounts, adapters, path, extras) to /v1/:chain/swap.

Each aggregate3 holds up to 16 candidates, 64 in total. A candidate that uses UniswapV4 costs 20–30M gas, so it gets its own call, and a plan carries at most 3 of them. If your node rejects a call, split it in half and retry. Candidates are ordered by the minimum known USD reserve along the path (score).

poolsPending: true means the server is still pulling pools for one of the tokens in the background, so the plan may be missing routes; request it again in a few seconds for a fuller plan. fallback is null on every supported chain. It is only set when the pair index is turned off for a chain; then eth_call it and decode the result as the return value of query.

{
  "code": 0,
  "data": {
    "chainId": 8453,
    "tokenIn": "0x…",
    "tokenOut": "0x…",
    "amountIn": "1000000000000000000",
    "path": { "tokenIn": "0x…", "tokenOut": "0x…" },
    "maxSteps": 3,
    "quoter": "0x27fe493F8A4F02e3049080d6aBD96646C7B1a666",
    "router": "0x1abe089620a6f3E3Ff802f2165AB8dbC10cd5CE8",
    "multicall3": "0xcA11bde05977b3631167028862bE2a173976CA11",
    "candidates": [
      {
        "id": 0,
        "kind": "direct",
        "tokens": ["0x…", "0x…"],
        "adapterIdx": [2],
        "adapters": [{ "index": 2, "address": "0x…", "name": "UniswapV3" }],
        "score": 8137595
      }
    ],
    "poolsPending": false,
    "calls": [{ "to": "0xcA11…", "data": "0x82ad56cb…", "candidateIds": [0, 1] }],
    "fallback": null,
    "split": {
      "mode": "auto",
      "steps": 10,
      "minGainBps": 5,
      "candidateIds": [0, 3],
      "calls": [{
        "to": "0xcA11…",
        "data": "0x82ad56cb…",
        "probes": [{ "candidateId": 0, "units": 1, "amountIn": "100000000000000000" }]
      }]
    }
  }
}

export const QUOTE_PLAN_ABI = [
  'function aggregate3((address target, bool allowFailure, bytes callData)[] calls) payable returns ((bool success, bytes returnData)[] returnData)',
  'function queryExactPath(uint256 amountIn, address[] tokens, uint8[] adapterIdx) view returns ((uint256[] amounts, address[] adapters, address[] path, uint256 gasEstimate, bytes[] extras) offer)',
  // only for a non-null fallback
  'function query(uint256 amountIn, address tokenIn, address tokenOut, uint256 maxSteps, address[] hopTokens, uint256 gasPrice) view returns ((uint256[] amounts, address[] adapters, address[] path, uint256 gasEstimate, bytes[] extras) offer)',
] as const

import { createPublicClient, decodeFunctionResult, http, parseAbi } from 'viem'
import { base } from 'viem/chains'

const abi = parseAbi(QUOTE_PLAN_ABI)
const client = createPublicClient({ chain: base, transport: http() })
const plan = (await (await fetch(planUrl)).json()).data

let best
for (const call of plan.calls) {
  const { data } = await client.call({ to: call.to, data: call.data })
  const rows = decodeFunctionResult({ abi, functionName: 'aggregate3', data: data! })
  rows.forEach((row, i) => {
    if (!row.success) return
    const offer = decodeFunctionResult({ abi, functionName: 'queryExactPath', data: row.returnData })
    const out = offer.amounts[offer.amounts.length - 1]
    if (out > 0n && (!best || out > best.amounts[best.amounts.length - 1])) best = offer
  })
}
if (!best) throw new Error('no route')

const offer = {
  amounts: best.amounts.map(String),
  adapters: best.adapters,
  path: best.path,
  extras: best.extras,
  gasEstimate: String(best.gasEstimate),
}
// POST { tokenIn, tokenOut, amountIn, to, offer } to /v1/:chain/swap

GET/v1/:chain/swap

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

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

Response adds minAmountOut, feeBps, and tx: { to, data, value }. Native tokenIn sets value = amountIn; ERC-20 input requires an allowance to the router first. A split quote encodes all of its legs into one Trade.

The router takes its fee out of amountIn before swapping, but the quote used the full amount, so minAmountOut removes the fee first. The server does not know who signs, so it assumes the larger fee:

feeBps       = max(fee, 10)
minAmountOut = floor(amountOut × (1 − feeBps / 10000) × (1 − slippage / 100))

amountOut = 990, slippage = 1, no fee → 990 × 0.999 × 0.99 = 979.12 → 979

POST/v1/:chain/swap

Builds swap calldata from an offer you already quoted (quotePlan or your own RXQuoter call). The server does not quote again and does not send an RPC for an ERC-20 in, ERC-20 out trade. The response matches GET /swap, with quoteMode: "client".

{
  "tokenIn": "0x…",
  "tokenOut": "0x…",
  "amountIn": "1000",
  "to": "0x…",
  "slippage": 0.5,
  "fee": 0,
  "offer": {
    "amounts": ["1000", "990"],
    "adapters": ["0x…"],
    "path": ["0x…", "0x…"],
    "extras": ["0x"],
    "gasEstimate": "120000"
  }
}

Checks: path starts at tokenIn and ends at tokenOut (native addresses are the wrapped native), amounts[0] equals amountIn, every adapter is on the chain whitelist, and extras are hex. adapters may be addresses or { address }. minAmountOut is the last amount less the fee and slippage, as in GET /swap; the router enforces it on-chain.

{
  "tokenIn": "0x…", "tokenOut": "0x…", "amountIn": "1000", "to": "0x…", "slippage": 0.5,
  "legs": [
    { "split": 6000, "offer": { "amounts": ["600", "595"], "adapters": ["0x…"], "path": ["0x…", "0x…"], "extras": ["0x"] } },
    { "split": 4000, "offer": { "amounts": ["400", "396"], "adapters": ["0x…"], "path": ["0x…", "0x…"], "extras": ["0x"] } }
  ]
}

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.

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

GET/healthz

Health check. No API key. Returns 200 while the process is up; status is "degraded" and reasonslists why when PocketBase is not ready, an RPC breaker is not closed, or an enabled chain's pair index is empty or stale.

{
  "status": "degraded",
  "reasons": ["pair-index stale on base"],
  "uptimeSec": 86400,
  "pocketbase": { "ready": true, "lastError": null },
  "breakers": { "8453": { "state": "closed", "total": 12, "failures": 0, "failRate": 0 } },
  "pairIndex": { "8453": { "enabled": true, "pairs": 1520, "lastBuildAt": 1760900000000, "lastError": null, "stale": true } }
}

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 RXQuoter legs + Circle Iris fees). Override the history host with crossApiUrl.

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

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

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