Normalize token identifiers
Use chain-aware identifiers and verified contract addresses. Symbols are display labels, not primary keys. Store decimals, native-token conventions, and token metadata with a clear source and refresh policy.
Swap API
Design the quote-to-execution path as a state machine.
A swap API is not only a price endpoint. A production integration must manage token identity, allowances, quote expiry, chain state, transaction construction, status tracking, errors, and user disclosure.
Route map
Turn a broad swap idea into a verifiable sequence.
The practical work is to identify the exact assets, networks, contracts, permissions, costs, and fallback behavior. The cards below form a repeatable review.
Separate indicative price and executable quote
An indicative price can support discovery, while an executable quote includes a specific amount, route, fee model, allowance target, transaction payload, and expiry. Label the difference in the user interface.
Handle allowances explicitly
Expose the exact spender and requested amount. Distinguish allowance transactions from swap transactions, track pending state, and support permit-based flows only when the token, wallet, chain, and API route support them.
Revalidate before signing
Balances, allowances, gas estimates, liquidity, block state, and quotes can change. Refresh or validate the quote immediately before the wallet signs and prevent stale data from appearing executable.
Track transaction lifecycle
A submitted hash is not a completed swap. Track pending, confirmed, reverted, replaced, dropped, and partially completed cross-chain states. Present actionable recovery steps without claiming certainty.
Instrument and protect the integration
Log quote identifiers, sources, fees, errors, and latency without collecting unnecessary secrets. Protect API keys server-side when required, validate all responses, set limits, and monitor contract or endpoint changes.
Questions to resolve
Frequently asked questions
Can a swap API key be placed in client-side code?
It depends on the provider and key privileges. Treat keys as secrets unless the provider explicitly designs them for public use and supports restrictive controls.
What should be cached?
Static token metadata can be cached with validation, while executable quotes, balances, allowances, gas data, and transaction payloads are time-sensitive.
Why does a quote endpoint return an allowance target?
The swap contract or allowance manager needs permission to spend the source token. The integration must use the exact target returned for the selected flow.
How should failed transactions be handled?
Show the on-chain status, preserve the quote and transaction context, explain likely causes, and provide safe next steps. Do not automatically resubmit without explicit user action.