Core Concepts

A short tour of the ideas the rest of the docs assume. If you've read How Swapper Works, this fills in the vocabulary.

Integrator

You. An integrator is any app that embeds the Swapper widget. Each integrator has a registered integratorId that ties a session to your configuration, your fee arrangement, and your webhook endpoint. Contact Swapper to get one (see Support).

Destination

The destination is the outcome you want, described by three values:

• dstChainId — the chain funds arrive on.

• dstTokenAddr — the token you receive there (0x0…0 = native).

• depositWalletAddress — the wallet that receives it.

No matter what the user pays with, Swapper normalizes it to this destination.

Source

What the user actually pays with — a card charge, USDC on Arbitrum, ETH on Ethereum, SOL on Solana, etc. Sources span multiple ecosystems (EVM, Solana, and more). The set of sources that can reach a given destination is determined by Swapper's routing engine.

Deposit methods

The three ways a user can fund, chosen on the widget's home screen:

Method	Key	In short
Pay with card	depositWithCash	Fiat on-ramp → crypto → your token
Transfer crypto	transferCrypto	One-tap smart-wallet deposit & swap
Wallet deposit	walletDeposit	Send from the user's own wallet, any chain

You can show all of them or restrict the set with supportedDepositOptions. See Deposit Methods for the details of each.

Route

For crypto funding, Swapper computes a route: the cheapest/best path to swap and (if needed) bridge the source into the destination token. A route quote includes the estimated and minimum output, the fees, and the exact transactions to sign.

The deposit record

Every completed funding produces a deposit — a unified record that captures the source asset, the destination asset, the tx hashes involved, and a lifecycle status. It's what you receive in a webhook. Its method is one of onramp, smart_wallet, or dex_swap.

Two notification channels

Swapper tells your app a deposit happened in two independent ways:

• Widget events — a postMessage to the parent page, in the browser, the instant it succeeds.

• Webhooks — a signed HTTP callback to your server when the deposit completes.

Use the event for instant UX and the webhook as your reliable source of truth.

Amounts are base-unit strings

Everywhere Swapper reports a token amount — in webhooks, in events — it is the integer amount in the token's smallest unit, serialized as a string: wei for 18-decimal tokens, 1_000_000 for 1 USDC (6 decimals), lamports for Solana. Never a float. Parse with a big-integer library. Prices and USD values are decimal strings.

The widget is hosted; you embed it

The deposit UI is a hosted app at https://deposit.swapper.finance. Your integration loads it in a sandboxed iframe via the iframe SDK, configured with the same four required parameters. See Choosing an Integration.