Glossary

Quick reference for the terms you'll meet across these docs and the SDK.

Integrator

Any app embedding the Swapper widget. Identified by an integratorId.

integratorId

Your registered integrator identity. Scopes a widget session to your config and links your webhook endpoint.

Destination

The dstChainId + dstTokenAddr + depositWalletAddress triple describing what you want to receive and where. See Core Concepts.

Source

Whatever the user funds with — a card payment or a token on some chain — before Swapper converts it to your destination token.

Deposit method / deposit option

One of the funding flows: depositWithCash (card), transferCrypto, or walletDeposit. Controlled with supportedDepositOptions.

Route

The computed swap/bridge path from a source to the destination — the widget quotes it, along with the transactions to sign and the fee breakdown.

Deposit (record)

The unified record of a completed funding: source & destination assets, tx hashes, and lifecycle status. Its method is onramp, smart_wallet, or dex_swap.

On-ramp

A fiat-to-crypto payment (card, Apple Pay, bank transfer) provided through Swapper's on-ramp partner. Backs the depositWithCash method.

Smart wallet

A per-user account-abstraction wallet (deployed via ZeroDev / EIP-7702) that lets a user deposit and swap in a single tap, and can sweep on-ramp funds onward. Backs the transferCrypto option (deposit method smart_wallet).

Custom contract call

An extra on-chain action executed after the swap — approve, stake, wrap, provide liquidity — configured with customContractCalls. See Custom Contract Calls.

ContractCallType

How a custom call treats amounts: DEFAULT (0), FULL_TOKEN_BALANCE (1), FULL_NATIVE_BALANCE (2), COLLECT_TOKEN_BALANCE (3).

Widget event

A postMessage the iframe fires to the parent page (envelope type: "SWAPPER_EVENT"). Names: transaction_success, resize, close_request. See Widget Events.

Webhook

A signed server-to-server HTTP callback fired when a deposit completes (eventType: transaction.completed). See Webhooks.

X-Webhook-Signature

The HMAC-SHA256 (Base64) signature header on every webhook request, computed over the raw body with your integrator secret. Verify it before trusting a payload.

Base unit

The smallest integer unit of a token (wei, lamports, 1e6 for USDC). All amounts in events and webhooks are base-unit strings.

Ecosystem

A family of chains that share an address/transaction format: evm, solana, starknet, fast.

Iframe SDK — @swapper-finance/deposit-sdk

The package that embeds the hosted widget as an iframe, modal, or inline embed. The only package you install to integrate Swapper.

actionLabel

UI wording mode: "buy" (default — "Buy with Fiat") or "deposit" ("Deposit with Fiat").

depositWalletAddress

The wallet that receives the destination token. Not a Swapper-custodied account — it's yours.