@provable-games/on-ramp-sdk

A slim wrapper over Swapper Finance's deposit widget for funding Starknet wallets with a card. Users buy USDC with a debit/credit card, Apple Pay, or a crypto transfer, delivered to their Starknet address — Swapper handles the on-ramp providers, cross-chain routing, and compliance.

The wrapper fills in the Starknet defaults (dstChainId, USDC token) and your integrator config, so an integration is a couple of lines.

Install

pnpm add @provable-games/on-ramp-sdk @swapper-finance/deposit-sdk

@swapper-finance/deposit-sdk is a peer dependency (it renders the widget).

Quick start

import { createSwapperDeposit } from "@provable-games/on-ramp-sdk";

const deposit = createSwapperDeposit({ integratorId: "YOUR_INTEGRATOR_ID" });

// In a click handler — opens the widget in a modal, USDC on Starknet by default:
const modal = deposit.openModal({
  depositWalletAddress: player.address, // the connected Starknet wallet
  onEvent: (e) => console.log("swapper event", e),
});
// modal.close();

// Or embed it inline in a container element:
deposit.mount("#deposit-container", { depositWalletAddress: player.address });

The integratorId is issued by the Swapper team and is a public (client-side) identifier — there's no separate API key.

Config

createSwapperDeposit(config):

| Field | Default | Notes | | --- | --- | --- | | integratorId | — (required) | Your Swapper integrator id | | chainId | "starknet" | Swapper destination chain id | | tokenAddresses | Starknet USDC/STRK/ETH | Override the per-asset dstTokenAddr | | styles | — | Widget theming (themeMode + componentStyles) | | minDepositUsd / maxDepositUsd | — | Deposit limits | | supportedDepositOptions | — | card / crypto transfer / wallet | | webhookUrl | — | Called on transaction.completed |

openModal(params) / mount(container, params):

| Field | Default | Notes | | --- | --- | --- | | depositWalletAddress | — (required) | Destination Starknet address | | asset | "USDC" | USDC / STRK / ETH | | customContractCalls | — | Post-swap contract calls | | onEvent | — | transaction_success / close_request |

Styling

createSwapperDeposit({
  integratorId,
  styles: {
    themeMode: "dark",
    componentStyles: {
      primaryColor: "#92FF66",
      primaryButtonTextColor: "#0F190D",
      accentColor: "#80E0A9",
      sphereColor: "#15EB17",
    },
  },
});

Note: the SDK's ComponentStyles (v0.2.x) uses primaryButtonTextColor, not primaryTextColor.

Starknet tokens

STARKNET_TOKEN_ADDRESSES holds the defaults used for dstTokenAddr. USDC is the token Swapper delivers on Starknet (0x033068…35fb, symbol "USDC", 6 decimals). The separate older "USD Coin" deployment (0x053c91…368a8) is exported as STARKNET_USD_COIN for reference — make sure your vault / liquidity references the same USDC you deposit in.

Example app

A runnable Vite + React demo lives in examples/react-vite: connect a Cartridge Controller, then fund it via Swapper. Set VITE_SWAPPER_INTEGRATOR_ID to enable the widget.

cd examples/react-vite
pnpm install
pnpm dev

Development

pnpm install
pnpm build       # tsup → dist (ESM + CJS + d.ts)
pnpm test        # vitest
pnpm typecheck   # tsc --noEmit

License

MIT