End-to-end V5 integration

Discover what can move

GET /v1/capabilities answers "what can I move between these two chains right now" — and, importantly, tells you why anything unavailable is unavailable rather than silently omitting it.

const params = new URLSearchParams({
  originChainId: "42161",
  destinationChainId: "8453",
  include: "tokens",
});

const res = await fetch(`${BASE}/v1/capabilities?${params}`, { headers: auth });
const capabilities = await res.json();

Useful query parameters:

Take the decimals for the token you selected from this response. Amounts everywhere else are integers in base units, sent as strings — and decimals for the same asset differ per chain, so never hardcode them.

Price the transfer

POST /v1/quotes prices one exact transfer and returns the payload to sign.

Which side carries the amount depends on amountType:

exact_input is the only mode that may leave amountType off. The other two must name it explicitly.

const quoteRes = await fetch(`${BASE}/v1/quotes`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({
    origin: {
      token: { chainId: 42161, address: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831" },
      amount: "1000000", // 1 USDC, 6 decimals
      depositor: "0x1111111111111111111111111111111111111111",
    },
    destination: {
      token: { chainId: 8453, address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
      recipient: "0x1111111111111111111111111111111111111111",
    },
    amountType: "exact_input",
    fundingMethods: ["permit2"],
  }),
});

const quote = await quoteRes.json();

You can request approval, permit2 or erc3009. The remaining funding methods — deposit_address, account_abstraction, contract — are chosen by the server and returned on the quote rather than requested.

Execute the quote

The quote comes back with nextActions: an ordered list of things that have to happen before the transfer can proceed. Dispatch on kind:

For a permit2 or erc3009 quote you get a sign action. Sign its typedData verbatim — that exact payload is what the server verifies — then submit the signature:

const signAction = quote.nextActions.find((a) => a.kind === "sign");

const signatures = {
  [signAction.id]: await walletClient.signTypedData(signAction.typedData),
};

const execRes = await fetch(`${BASE}/v1/quotes/${quote.quoteId}/executions`, {
  method: "POST",
  headers: { ...auth, "Content-Type": "application/json" },
  body: JSON.stringify({ authorization: { signatures } }),
});

const execution = await execRes.json();

The response carries executionId, transferId, quoteId and acceptedAt.

A 2xx here means the transfer was accepted, not that it has arrived.

Track it to a settled outcome

Transfer status needs no API key:

const transferRes = await fetch(`${BASE}/v1/transfers/${execution.transferId}`);
const transfer = await transferRes.json();

console.log(transfer.status);
// { state, reason, description, isTerminal, finalized }

GET /v1/transfers lists transfers newest-first with keyset pagination when you need more than one.

Reading status

status.state is the coarse outcome and status.reason is the granular one. Each reason maps to exactly one state:

Two fields decide when to stop polling:

• isTerminal — Across will take no further action on this transfer.
• finalized — the chain state behind it can no longer reorg.

status.description is a support-safe sentence you can surface directly to a user. Branch your own logic on state and reason, never on description.