> 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, 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](/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 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](/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`) — 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](/deposit-methods/transfer-crypto.md).
* **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](/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; your `integratorId` is what scopes a session.