Core Concepts

xPath separates route discovery from transaction execution. Understanding that boundary makes integrations easier to validate and safer to operate.

Quote

A quote is a ranked route candidate returned by GET /quote. It describes:

• the source and destination assets
• input, expected output, and minimum output amounts
• fees and estimated gas cost
• providers used by the route
• ordered execution legs
• route kind and estimated completion time
• a quoteId for follow-up operations

A quote is not an onchain transaction. Build it before asking the wallet to execute.

Route Kinds

Route Ranking

The standard quote endpoint supports these routeMode values:

Gasless quotes use rankingMode: value_max, speed_max, or balanced.

Do not assume the first route is always appropriate for every user. Compare output, minimum output, fees, time, provider policy, and route complexity.

Amounts and Decimals

All token amounts are integer strings in the token's smallest unit:

import { parseUnits } from 'viem'

const amount = parseUnits('10', 6).toString() // 10 USDC

Use token decimals returned by /tokens or /search-token. Never calculate amounts from display symbols alone.

Slippage and Minimum Output

slippage is expressed as a percentage. For example, 1 means 1%.

The quote's amountOut is the expected output. minAmountOut is the protected minimum after slippage. Before building or executing:

• reject expired quotes
• show both values to the user
• pass the selected route's minimum output into the build request
• rebuild when market movement makes the quote stale

Providers and Path

providers is the flattened set of DEX and bridge integrations used by a route. path contains the ordered execution legs.

Use provider filters only when product policy requires them:

• includeProvider restricts planning to an allowlist
• excludeProvider removes providers from consideration

Provider availability can vary by chain, asset, amount, and time. Treat quote responses as the source of truth for the selected transaction.

Build Path

POST /build-path turns route inputs into a source-chain transaction:

Do not modify to or data. Verify the chain, expiry, recipient, amount, and allowance target before execution.

Token Acquisition Modes

The route executor supports multiple ways to acquire the input token:

Use the dedicated gasless endpoints for modes 2 and 3.

Approval Versus Permit2 Signature

These are separate permissions:

1. ERC-20 approval authorizes an allowance target to transfer tokens.
2. A Permit2 EIP-712 signature authorizes a specific signed transfer.

A gasless flow may still require a one-time onchain ERC-20 approval to the Permit2 contract. The swap itself can then be relayed without the user paying its gas.

Execution Status

For standard routes, call /status with the source transaction hash and source chain. The response can include:

• source and destination transaction details
• provider information
• route kind
• current status
• source and destination assets

For gasless routes, poll /gasless/status with the returned swapId.

Use a delay and timeout when polling. Treat terminal failure as a user-visible state and retain the transaction identifiers for support.

Integration Rules

• Fetch chains and tokens dynamically instead of hardcoding support.
• Validate token address and chain ID together.
• Keep amounts as strings or bigint; do not use floating-point arithmetic.
• Requote after expiry or before delayed execution.
• Approve only the returned allowance target and only the required amount when practical.
• Never expose private keys or API keys in frontend bundles.