> For the complete documentation index, see [llms.txt](https://docs.swapper.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.swapper.finance/getting-started/how-swapper-works.md).

# 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 to a deposit address (QR), or a connected wallet.
* **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](/tracking-deposits/widget-events.md) and [webhook](/tracking-deposits/webhooks.md).

## 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 endpoints (set in the [Integrator Dashboard](/integrator-dashboard/overview.md)). |
| `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](/widget-integration/configuration.md).

## The three funding methods

The user chooses on the widget's home screen; you can restrict which appear with [`supportedDepositOptions`](/widget-integration/configuration.md#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](/deposit-methods/fiat-onramp.md).
* **Transfer crypto** (`transferCrypto`, "…with QR") — the widget shows a deposit address and QR code; the user sends tokens to it from any wallet or exchange, on any supported chain including Bitcoin, Solana and Tron. No wallet connection needed. On EVM chains the address is the user's own smart wallet; Swapper swaps and bridges what arrives to your destination. See [Transfer Crypto (QR)](/deposit-methods/transfer-crypto.md).
* **Wallet deposit** (`walletDeposit`, "…with Wallet") — the user connects their own EVM or Solana wallet and signs the route (approve + swap, or one Solana transaction). See [Wallet Deposit](/deposit-methods/wallet-deposit.md).

## 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**](/tracking-deposits/widget-events.md) — a `postMessage` fired to the parent page the moment a deposit succeeds. Great for updating the UI.
* [**Webhooks**](/tracking-deposits/webhooks.md) — 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.

{% hint style="info" %}
Use **both**: the widget event for instant UX, the webhook for reliable accounting. They describe the same deposit from two vantage points.
{% endhint %}

## 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 the widget — your public `integratorId` identifies you and scopes a session. API keys are optional and only for calling the [API](/api-v1/overview.md) from your servers (higher rate limits, [integrator fees](/api-v1/integrator-fees.md)); see [Authentication](/api-v1/authentication.md).