How Swapper Works

Swapper sits between however your user has money today and the exact token your app wants to receive. This page explains that flow end to end — nothing here is required to integrate, but it makes the rest of the docs click.

The one-sentence version

You declare a destination (chain + token + wallet); the user picks a funding method; Swapper does the on-ramp / bridge / swap and delivers your token; you get notified when it lands.

The pieces

Four moving parts sit between your user and your wallet:

• Your app — embeds the widget with the four required parameters (integratorId, dstChainId, dstTokenAddr, depositWalletAddress).

• The funding method the user picks — card on-ramp, crypto transfer, or wallet deposit.

• The Swapper backend — routing, pricing, and deposit tracking; it swaps and bridges the funds to your destination token.

• Your destination wallet — receives the token, and the outcome is reported back to your app by widget event and webhook.

The four required parameters

Every integration is configured with exactly four things:

Parameter	What it is
integratorId	Your registered identity. Ties the session to your config, fees, and webhook endpoint.
dstChainId	The chain you want to receive funds on (e.g. "8453" for Base).
dstTokenAddr	The token you want to receive on that chain (0x0…0 for native).
depositWalletAddress	The wallet that should receive the destination token.

Everything else — styling, deposit-method selection, limits, custom calls — is optional. See the Configuration Reference.

The three funding methods

The user chooses on the widget's home screen; you can restrict which appear with supportedDepositOptions.

• Pay with card (depositWithCash) — a fiat on-ramp (card / Apple Pay / bank) turns cash into crypto, which is then swapped to your destination token. See Pay with Card.

• Transfer crypto (transferCrypto) — a smart-wallet / account-abstraction flow that lets a user deposit and swap in a single tap, and can even sweep an on-ramp onward automatically. See Transfer Crypto.

• Wallet deposit (walletDeposit) — the user sends tokens from their own wallet on any supported chain; Swapper bridges and swaps to your destination. See Wallet Deposit.

Asynchronous by nature

Cross-chain routing, on-ramp settlement, and swap confirmation don't all happen in the same instant. The widget guides the user through each step and shows progress; your app learns the final outcome through two independent channels:

• Widget events — a postMessage fired to the parent page the moment a deposit succeeds. Great for updating the UI.

• Webhooks — a signed server-to-server callback when a deposit completes. Use this as your source of truth for crediting accounts; browsers can be closed, servers don't miss the event.

Use both: the widget event for instant UX, the webhook for reliable accounting. They describe the same deposit from two vantage points.

What Swapper does not do

• It never takes custody of your users' funds between steps beyond what the swap itself requires — routing is executed from the user's wallet or a per-user smart wallet.

• It doesn't hold your destination funds — they go straight to depositWalletAddress.

• It doesn't require an API key to render; your integratorId is what scopes a session.