Token Swap API
Execute on-chain DEX swaps and cross-chain bridges from your customers' WaaS wallets — all through a single, unified API endpoint.
Overview
The Swap API lets you swap any token in a customer's wallet for any other token, including across different blockchains. The routing logic is handled automatically:
- Same-chain swap — executed on-chain through the FiatSwapV2 smart contract (Polygon or BSC), routed via QuickSwap / PancakeSwap
- Cross-chain bridge — executed through LiFi, covering 20+ EVM-compatible chains
Your integration sees one API. You call the same endpoints whether you're swapping USDC → MATIC on Polygon or bridging USDT from Polygon to Arbitrum.
How Routing Works
flowchart TD
A["POST /api/v1/swap/:customerID"] --> B{Same chain?}
B -- "Yes (POL or BSC)" --> C[FiatSwapV2 Contract<br/>QuickSwap / PancakeSwap]
B -- "No (cross-chain)" --> D[LiFi Bridge<br/>20+ chains]
C --> E[Tx Hash returned]
D --> E| Pair | Route | Settlement time |
|---|---|---|
| Token → Token on Polygon | FiatSwapV2 → QuickSwap / SushiSwap | ~30 seconds |
| Token → Token on BSC | FiatSwapV2 → PancakeSwap / SushiSwap | ~30 seconds |
| Polygon → BSC (or any other chain) | LiFi bridge | 1–10 minutes |
| Any EVM chain → Any EVM chain | LiFi bridge | 1–10 minutes |
Smart Contracts
Polygon (ChainID 137)
| Contract | Address |
|---|---|
| FiatSwapV2 Proxy | 0x46C75Ead09F097b7fd191998761711D99E48A72C |
| QuickSwap Router | 0xa5E0829CaCEd8fFDD4De3c43696c57F7D7A678ff |
| SushiSwap Router | 0x1b02dA8Cb0d097eB8D57A175b88c7D8b47997506 |
| WMATIC | 0x0d500B1d8E8eF31E21C99d1Db9A6444d3ADf1270 |
BSC (ChainID 56)
| Contract | Address |
|---|---|
| FiatSwapV2 Proxy | 0xB18db6872DA839122d38A2616f8D4FD56533e130 |
| PancakeSwap Router | 0x10ED43C718714eb63d5aA57B78B54704E256024E |
| SushiSwap Router | 0x1b02dA8Cb0d097eB8D57A175b88c7D8b47997506 |
| WBNB | 0xbb4CdB9CBd36B01bD1cBaEBF2De08d9173bc095c |
Platform Fee
FiatSwapV2 charges a platform fee on every on-chain swap. The fee rate is read directly from the contract (calculatePlatformFee). The quote response shows the exact fee before you execute.
For LiFi bridge swaps, fees are set by the bridge protocols and shown in the platform_fee field of the quote.
Key Concepts
from_token / to_token — ERC-20 contract addresses in checksum format. Pass "native" (or the empty string "") to use the chain's native coin (MATIC on Polygon, BNB on BSC).
amount_in — always in base units (wei / smallest denomination). For 1 USDC (6 decimals) pass "1000000". For 1 MATIC (18 decimals) pass "1000000000000000000".
amount_out_min — slippage protection floor, also in base units. Get this from the quote's to_amount_min field. If omitted, defaults to 1 (no slippage protection — not recommended for production).
status: "pending" — swap execution broadcasts the transaction and returns immediately. The transaction settles on-chain asynchronously. Use the tx_hash to check the final status on the blockchain explorer.
Swap Record Status
| Status | Meaning |
|---|---|
pending | Transaction broadcast, awaiting on-chain confirmation |
confirmed | Transaction confirmed on-chain |
failed | Transaction reverted or bridge failed |
API Endpoints
| Method | Path | Auth | Description |
|---|---|---|---|
| GET | /api/v1/swap/quote | API Key | Get a price quote before executing |
| POST | /api/v1/swap/:customerID | API Key | Execute a swap from a customer wallet |
| GET | /api/v1/swap/:customerID/history | API Key | Customer swap history |
| GET | /api/v1/swap/analytics/overview | JWT | Merchant dashboard summary |
| GET | /api/v1/swap/analytics/transactions | JWT | All swaps across all customers |
| GET | /api/v1/swap/analytics/volume | JWT | Daily swap volume chart data |