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 actions to execute it.

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",
  }),
});

const quote = await quoteRes.json();

You don't name a funding method. The server picks one of approval, permit2 or erc3009 from what your client can do — declare that with capabilities.operations, and narrow it with authorizationPolicy.allowedTypes — and returns the matching nextActions. Sending the old fundingMethods field is rejected with 400 request.unsupported_param.

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_typed_data 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_typed_data");

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

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

const execution = await execRes.json();

The response carries orderId, acceptedAt and, when a fresh balance reading was taken, balanceCheck.

For an approval quote, the actions are an approve_token (omitted when the allowance already covers the amount) and a send_transaction with id: "prefunded-store", the deposit itself. There is no submit_execution: send the approval, then the deposit, and the transfer starts once the deposit lands on chain. Don't POST to the executions endpoint for it. The Quickstart has both flows as code.

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

Track it to a settled outcome

Track the transfer with the same key:

const transferRes = await fetch(`${BASE}/v1/transfers/${execution.orderId}`, {
  headers: auth,
});
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:

A transfer with destinationActions completes as filled_destination_action_successful or filled_destination_action_failed, never plain filled.

isTerminal is the stopping signal — poll about every 5 seconds and stop when it is true. finalized reports that the chain can no longer revise the outcome; a normal integration does not need to wait for it.

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.