What We’re Building
A server-side flow that swaps tokens using Dynamic’s Swap API directly. By the end of this guide you will be able to:- Get a swap quote with route, fees, and a ready-to-sign payload
- Handle ERC-20 token approvals when required
- Sign and broadcast the swap transaction on-chain
- Poll for cross-chain completion
Prerequisites
- A Dynamic environment
- A wallet with private key access (for signing)
- Node.js 18+ (or any runtime with
fetch)
Base URL
All swap endpoints live under:Overview
The swap flow is two API calls plus one on-chain transaction:The Swap API is stateless — there is no session token or transaction state to manage. Each call is independent.
Step 1: Get a Swap Quote
Request a quote by specifying the source and destination tokens. The API finds the best route and returns asigningPayload you can send directly on-chain.
Request Fields
| Field | Type | Description |
|---|---|---|
from.address | string | Wallet address sending the tokens |
from.chainName | string | Chain family: "EVM", "SOL", "BTC", "SUI" |
from.chainId | string | Network ID (e.g., "1" for Ethereum, "137" for Polygon) |
from.tokenAddress | string | Token contract address. Use 0x0000000000000000000000000000000000000000 for native tokens on EVM |
from.amount | string | Amount in smallest unit (e.g., "10000000" = 10 USDC). Mutually exclusive with to.amount |
to.address | string | Wallet address receiving the tokens |
to.chainName | string | Destination chain family |
to.chainId | string | Destination network ID |
to.tokenAddress | string | Destination token contract address |
to.amount | string | Desired output amount. Mutually exclusive with from.amount |
slippage | number | Max slippage as a decimal (e.g., 0.005 = 0.5%). Optional |
order | string | Route preference: "FASTEST" or "CHEAPEST". Optional |
maxPriceImpact | number | Hide routes above this price impact (e.g., 0.15 = 15%). Optional |
Response
signingPayload contains the to, data, and value fields needed to submit the transaction on-chain.
For cross-chain swaps, the steps array shows each hop (bridge + swap), so you can display the full route to users.
Step 2: Sign and Broadcast
Use thesigningPayload from the quote to submit an on-chain transaction. This example uses viem, but any signing library works.
Handle ERC-20 Approval
If you’re swapping an ERC-20 token (not a native token), you may need to approve the router to spend your tokens first. Check whether the router already has sufficient allowance — if not, send an approval transaction before the swap.approve.ts
Send the Swap Transaction
swap.ts
Step 3: Poll for Status
For cross-chain swaps, use the status endpoint to track completion. For same-chain swaps, the transaction receipt alone is sufficient.Response
Status Values
| Status | Description |
|---|---|
PENDING | Swap in progress |
COMPLETED | Swap finished successfully |
FAILED | Swap failed |
Substatus Values (When Pending)
| Substatus | Description |
|---|---|
WAIT_SOURCE_CONFIRMATIONS | Waiting for source chain confirmations |
WAIT_DESTINATION_TRANSACTION | Waiting for destination chain transaction |
BRIDGE_NOT_AVAILABLE | Bridge temporarily unavailable |
REFUND_IN_PROGRESS | Refund is being processed |
status is COMPLETED or FAILED.
Complete Example
A self-contained TypeScript script that gets a quote, signs, broadcasts, and polls for completion:swap-example.ts
Cross-Chain Example
Swap USDC on Ethereum to MATIC on Polygon — the API handles bridging automatically:cross-chain-swap.ts
Cross-chain swaps may take longer to complete. The
steps array in the quote shows each bridge and swap hop along the route.Supported Chains and Native Tokens
The Swap API supports the following chains (mainnet only). Use these values forchainName, chainId, and native token addresses in your requests.
Chain Reference
| Chain | chainName | chainId | Networks |
|---|---|---|---|
| EVM | "EVM" | Standard EVM chain ID (e.g., "1" for Ethereum, "137" for Polygon, "8453" for Base, "42161" for Arbitrum, "10" for Optimism) | All major EVM networks |
| Solana | "SOL" | "101" | Solana mainnet |
| Bitcoin | "BTC" | "1" | Bitcoin mainnet |
| Sui | "SUI" | "501" | Sui mainnet |
Native Token Addresses
For native tokens (ETH, SOL, BTC, SUI), use any of the accepted addresses below in thetokenAddress field:
| Chain | Accepted native token addresses |
|---|---|
| EVM | 0x0000000000000000000000000000000000000000 (zero address) or 0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee |
| Solana | 11111111111111111111111111111111 (System Program) or So11111111111111111111111111111111111111112 (Wrapped SOL) |
| Bitcoin | 11111111111111111111111111111111 or bitcoin |
| Sui | 0x2::sui::SUI or 0x0000000000000000000000000000000000000000000000000000000000000002::sui::SUI |
0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 for USDC on Ethereum).
Error Handling
| Status | Cause | Recovery |
|---|---|---|
400 | Missing or conflicting amount fields | Provide exactly one of from.amount or to.amount |
422 | Unsupported chain | Check from.chainName is supported |
5xx | Provider or infrastructure error | Retry with exponential backoff |
Tips
- Quote freshness: Quotes are snapshots — prices and gas can shift. Sign promptly after receiving a quote.
- Slippage: Set slippage based on token liquidity. Stablecoins work well at
0.005(0.5%), volatile pairs may need0.01or more. - Order preference: Use
"CHEAPEST"to minimize fees or"FASTEST"to reduce execution time. Cross-chain routes benefit the most from this. - Price impact: Set
maxPriceImpactto filter out routes that would move the market too much for your trade size.
Related
- Checkout via API — Accept payments with automatic cross-chain settlement
- Cross-chain swaps with LI.FI — Frontend integration with LI.FI widget
getSwapQuote— JavaScript SDK swap quote referenceexecuteSwapTransaction— JavaScript SDK swap execution reference