Money and settlement
Use integer strings for money that moves. USD fields help a user understand a route; they are not settlement evidence.
Amount rules
| Field family | Representation | Use it for |
|---|---|---|
Request amounts such as fromAmount and toAmount | Positive base-10 atomic-unit string | User input after conversion with the source token decimals. |
Quote fromAmount, toAmount | Atomic-unit string | A current public estimate only; never an execution floor. |
Created swap depositAmount, expectedOutput | Atomic-unit string | The exact funding instruction and the public display estimate. |
Completed actualOutput and bridge settlement amounts | Atomic-unit string with the paired decimals field | Settlement display and reconciliation. |
amountUsd, quote USD fields, fee USD fields | Display valuation | Never use to settle or calculate an on-chain transfer. |
Get token decimals from featuredTokens in GET /v2/swaps/assets, GET /v2/swaps/assets/tokens, the created order's token metadata, or the bridge settlement amount object. Never send a JavaScript floating-point amount to the API.
Funding instruction wins
A quote is not a deposit instruction. After creating an order, show the returned funding address, amount, token metadata, and expiry exactly as returned. Do not reconstruct an address or payment amount from the quote.
Direct native-bridge withdrawals are intentionally amountless at creation: the eventual payout is computed from the wrapped amount actually observed. When present, bridgeSettlement.input and bridgeSettlement.output are the authoritative atomic settlement evidence.
Fees
Every public fee rate is a fraction: 0.005 means 0.5%.
The public swap quote includes only public fees. Execution separately freezes a private expectation after the resolved total service rate, integrator fees, explicit bridge fees, and exact customer-paid source costs. The configured end-to-end slippage percentage is applied once to that private final-output expectation. It is shared by LI.FI, Hyperliquid, preparation, settlement, and recovery; it is not granted once per stage. Neither the private expectation, its minimum, nor a hidden fee is returned before completion.
A separate, tighter per-leg percentage is what an individual route provider is told to tolerate. It sets that leg's own on-chain minimum and never the customer's floor; it is capped by the end-to-end budget, and a leg that cannot be quoted inside it is re-quoted at the full budget before the order gives up. No public field exposes either number.
Bridge minimums and flat-fee values are native display units; consult the exact generated schema and current GET /v2/bridges/terms response at creation time. Runtime configuration can change.
bridgeSettlement.fee is nullable. Do not imply that its absence proves there was no fee or invent a fee breakdown from other display values.
Coinflip outcomes
A completed order does not always mean the destination received an asset. If coinflip is enabled for the order, check coinflipLost and the final coinflip result before presenting a received amount.