FAQ

Integration

Which package do I install?

@swapper-finance/deposit-sdk — the iframe SDK. It works in any framework, or none, and is the only package you need to embed Swapper.

What's the minimum to get a widget on screen?

Four values — integratorId, dstChainId, dstTokenAddr, depositWalletAddress — passed to openSwapperModal or new SwapperIframe. See the Quick Start.

How do I get an integratorId?

Open a ticket in Discord — see Support. The same registration links your webhook endpoint and secret.

Can I change the destination or styling after the widget loads?

Yes. updateConfig(), updateStyles(), and updateCustomContractCalls() patch the live widget over postMessage — no reload. See the iframe SDK.

The first open is slow. Can I make it instant?

Preload it. Use preloadSwapperModal or preloadSwapperEmbed. The widget loads hidden in the background; smart-wallet authorization is deferred until the user actually opens it.

Deposits

What can users pay with?

A card / bank on-ramp, a one-tap smart-wallet deposit, or a wallet transfer from their own wallet on any supported chain. You choose which to offer with supportedDepositOptions.

What do I actually receive?

Exactly your dstTokenAddr on dstChainId, delivered to depositWalletAddress — regardless of what the user paid with.

Can I set deposit limits?

Yes — minDepositUsd / maxDepositUsd, validated against the USD value of the received amount. The transfer flow also floors the minimum so gas is always covered.

Can I run actions after the swap (stake, wrap, LP)?

Yes — Custom Contract Calls chain arbitrary on-chain actions after delivery, atomically.

Tracking

How do I know a deposit completed?

Two channels: a widget event in the browser (instant, for UX) and a webhook to your server (reliable, for accounting). Use both.

Why did I get two webhooks for one deposit?

A card on-ramp that is swept onward through a smart wallet produces two linked deposits (onramp + smart_wallet). Count the flow once, keyed by the funding tx. See Webhooks → Linking.

How do I verify a webhook is really from Swapper?

Check the X-Webhook-Signature header — HMAC-SHA256 (Base64) of the raw body with your secret. Code sample in Webhooks.

Are webhooks retried?

Once — an initial attempt plus one retry ~30s later. Deduplicate on eventId and return 200 within 10 seconds. See Delivery & idempotency.

Amounts & custody

What format are amounts in?

Base-unit strings (wei / lamports / smallest unit), never floats. Prices and USD values are decimal strings.

Can Swapper move my users' funds?

No, by design. Signing and broadcasting always happen from the user's own wallet or smart wallet, never a Swapper-held key.