Integrate the Deposit SDK

The Deposit SDK (@swype-org/deposit) opens Blink’s hosted deposit flow in a cross-origin iframe. Use the default overlay for a standalone deposit action, or render Blink inline inside a payment-method aggregator with the embedded presentation. The SDK handles the signer call, iframe lifecycle, passkey/WebAuthn delegation, adaptive sizing, and completion detection via postMessage.

Embedding Blink in an aggregator

Add Blink inside your own desktop payment panel, follow its reported size, and match your brand colors.

Install

npm install @swype-org/deposit

yarn add @swype-org/deposit

pnpm add @swype-org/deposit

JavaScript

import { Deposit, DepositError, getDisplayMessage } from '@swype-org/deposit';

const deposit = new Deposit({
  signer: '/api/sign-payment',
});

document.getElementById('transfer-btn')!.addEventListener('click', async () => {
  try {
    const { transfer: result } = await deposit.requestDeposit({
      amount: 50,
      chainId: 8453,
      address: '0x1a5FdBc891c5D4E6aD68064Ae45D43146D4F9f3a',
      token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    });
    console.log('Transfer complete:', result.id, result.status);
  } catch (error) {
    if (error instanceof DepositError) {
      showErrorToUser(getDisplayMessage(error));
    }
  }
});

React hook

import { useBlinkDeposit } from '@swype-org/deposit/react';

function TransferButton() {
  const { status, result, error, displayMessage, requestDeposit } = useBlinkDeposit({
    signer: '/api/sign-payment',
  });

  const handleTransfer = () => {
    requestDeposit({
      amount: 50,
      chainId: 8453,
      address: userWalletAddress,
      token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
    });
  };

  return (
    <>
      <button onClick={handleTransfer} disabled={status === 'signer-loading'}>
        {status === 'signer-loading' ? 'Preparing...' : 'Deposit $50'}
      </button>
      {error && <p className="error">{displayMessage}</p>}
      {result && <p>Transfer {result.transfer.id} complete!</p>}
    </>
  );
}

The hook returns reactive status, result, error, displayMessage, and isActive values, plus requestDeposit, focus, and close actions. It manages the Deposit lifecycle and cleans up on unmount.

Prebuilt deposit button

You don’t have to design your own button. The SDK ships BlinkDepositButton, a prebuilt Blink-branded button — a black pill with a “Deposit stablecoins / In a Blink” label and USDC/USDT coin marks. It is self-contained (inline styles, data-URI icons, no CSS imports) and fills the width of its container.

import { BlinkDepositButton, useBlinkDeposit } from '@swype-org/deposit/react';

function Checkout({ userWalletAddress }: { userWalletAddress: string }) {
  const { status, error, displayMessage, requestDeposit } = useBlinkDeposit({
    signer: '/api/sign-payment',
  });

  return (
    <>
      <BlinkDepositButton
        onClick={() =>
          requestDeposit({
            amount: 50,
            chainId: 8453,
            address: userWalletAddress,
            token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
          })
        }
        loading={status === 'signer-loading'}
      />
      {error && <p className="error">{displayMessage}</p>}
    </>
  );
}

The button is presentation-only — wire onClick to requestDeposit yourself, and pass disabled or loading to reflect your app’s state. Its branding is intentionally fixed; if you need a custom look, keep building your own button as shown above. See the BlinkDepositButton reference for the full props table.

Configuration

const deposit = new Deposit({
  // Required: URL string or custom async function
  signer: '/api/sign-payment',

  // Base URL of the hosted payment webview app.
  // Default: 'https://pay.blink.cash'
  webviewBaseUrl: 'https://pay.blink.cash',

  // Origin for postMessage validation. Derived from webviewBaseUrl when omitted.
  hostedFlowOrigin: 'https://pay.blink.cash',

  // DOM mount point. Required when presentation is 'embedded'.
  // Default for overlay: document.body
  containerElement: document.getElementById('transfer-root')!,

  // 'overlay' (default) or inline 'embedded' presentation.
  presentation: 'overlay',

  // Embedded only: maximum inline iframe height. Defaults to 90% of viewport.
  embedMaxHeightPx: 640,

  // Max ms to wait for signer response. Default: 15000
  signerTimeoutMs: 15_000,

  // Max ms for entire flow (signer + user completion). No limit by default.
  flowTimeoutMs: 300_000,

  // Allow the hosted flow to show the full widget (deposit address options
  // alongside Blink one tap). Set to false to send users straight to the
  // Blink one-tap flow. Default: true
  enableFullWidget: true,

  // Hosted UI theme, optional brand colors, and deposit title visibility.
  appearance: {
    theme: 'dark',
    hideDepositTitle: false, // Set true when your container supplies the heading.
    variables: {
      colorPrimary: '#0f62fe',
      colorBackground: '#101828',
      colorText: '#f7f9fc',
    },
  },

  // Warm a hidden flow after construction. Default: true
  preload: true,

  // Optional preload hint. Authorization still comes from the signer response.
  merchantId: MERCHANT_ID,

  // Enable debug logging. Default: false
  debug: false,
});

By default the hosted flow can open with the full widget — a deposit options entry screen that offers deposit addresses (pay from an exchange or any wallet) alongside Blink’s one-tap deposit. Set enableFullWidget: false to skip it and send every user straight to the Blink one-tap flow. The full widget only appears when both your SDK config and your Blink merchant account have it enabled. If it is disabled on your merchant account, the hosted flow stays in one-tap mode regardless of this option — contact Blink to change your account configuration.

Dark and light mode

The hosted deposit flow ships both a light and a dark palette. Pick one with the appearance.theme config:

const deposit = new Deposit({
  signer: '/api/sign-payment',
  appearance: { theme: 'dark' },
});

`theme`	Behavior
`'light'`	Always renders the light palette.
`'dark'`	Always renders the dark palette.
`'system'`	Follows the user’s OS `prefers-color-scheme`. Flips live if the user changes their device theme mid-flow.
(omitted)	Auto-detected from your page’s declared `color-scheme` — see below.

The theme applies to the whole flow, not just the modal: it is carried through every Blink surface the flow opens, including the top-level setup tab and wallet authorization pages.

Automatic detection from your page

When you pass no theme, the SDK reads the computed color-scheme of your page’s <html> element and matches it:

Your page declares	Flow defaults to
`color-scheme: dark`	`dark`
`color-scheme: light dark`	`system`
`light`, `only light`, `normal`, or nothing	`light`

So if your site already declares its color scheme, the modal matches it with zero configuration:

:root {
  color-scheme: light dark;
}

<meta name="color-scheme" content="light dark" />

Only declared color schemes are detectable. A page that paints dark colors — for example a .dark class that swaps CSS variables — but never sets color-scheme reads as light, and the modal renders light on your dark page. Either declare color-scheme or pass an explicit theme.

An explicit theme always wins over detection. appearance: { theme: 'light' } pins the light palette even on a page that declares itself dark.

Switching theme at runtime

The theme is read when the instance builds its hosted-flow URLs — including the warm-up iframe created at construction — so it is fixed for the life of a Deposit instance. To change it, destroy the instance and create a new one:

let deposit = new Deposit({ signer: '/api/sign-payment', appearance: { theme: 'light' } });

function setBlinkTheme(theme: 'light' | 'dark' | 'system') {
  deposit.destroy();
  deposit = new Deposit({ signer: '/api/sign-payment', appearance: { theme } });
}

With the React hook, the Deposit instance is created once on first render, so changing the appearance prop has no effect. Remount the component with a key instead:

function DepositWidget({ theme }: { theme: 'light' | 'dark' | 'system' }) {
  const { status, requestDeposit } = useBlinkDeposit({
    signer: '/api/sign-payment',
    appearance: { theme },
  });
  // ...
}

// Parent: changing `theme` remounts the widget with a fresh Deposit instance.
<DepositWidget key={theme} theme={theme} />

If your app simply follows the OS theme, prefer theme: 'system' over toggling between 'light' and 'dark'. The hosted flow subscribes to prefers-color-scheme itself, so it tracks the device theme with no remount and no warm-up iframe thrown away.

What theming does not cover

The modal’s dim backdrop behind the payment card is the same in both themes.
BlinkDepositButton is intentionally fixed Blink branding — a black pill — in both themes. Build your own trigger button if you need it to change with your theme.

Brand colors

appearance.variables accepts colorPrimary, colorBackground, colorText, colorDanger, and colorBorder. Use opaque #rgb or #rrggbb values. Blink derives the rest of its palette and enforces contrast for derived text colors. The variables theme Blink’s UI inside the cross-origin iframe. For an embedded aggregator integration, your CSS still owns the outer panel’s size, radius, background, border, and shadow.

Deposit titles

Set appearance.hideDepositTitle: true when your container already supplies a deposit heading. This hides the Deposit title on entry, progress, and completion screens for both Blink One Tap and manual/QR deposits. Selecting Settings still opens More with its title. Navigation controls, balances, status messages, and action labels remain visible. The default is false; omitting the property keeps the deposit titles visible.

const deposit = new Deposit({
  signer: '/api/sign-payment',
  appearance: { hideDepositTitle: true },
});

Custom signer function

If you need full control over the HTTP call to your signer (custom headers, auth tokens, different HTTP method), pass a function instead of a URL:

import type { SignerFunction } from '@swype-org/deposit';

const deposit = new Deposit({
  signer: async (data) => {
    const res = await fetch('/api/sign-payment', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${getSessionToken()}`,
      },
      body: JSON.stringify(data),
    });
    if (!res.ok) throw new Error(`Signer error: ${res.status}`);
    return res.json();
  },
});

Deposit request fields

Field	Type	Required	Description
`amount`	`number`	Yes	USD amount to deposit (> 0).
`chainId`	`number`	With `address`/`token`	Destination chain ID. Dynamic per user. For example, `8453` for Base or `792703809` for Solana.
`address`	`string`	With `chainId`	Destination wallet address. For the web SDK this can be an EVM address or a Solana address, depending on the destination chain.
`token`	`string`	With `chainId`	Destination token identifier. Use an EVM token contract address on EVM chains or an SPL mint address on Solana.
`destinations`	`Array<{ chainId, address, token }>`	Instead of the three above	Up to 10 accepted destinations, most-preferred first. See Multiple destinations.
`callbackScheme`	`string \| null`	No	Always `null` for browser integrations. Reserved for native app deep links.
`minimumDeposit`	`number \| null`	No	Your minimum deposit in USD. Raises Blink’s route minimum; never lowers it. Omit or pass `null` to use Blink’s minimum.
`reference`	`string`	No	Merchant order/invoice ID for reconciliation.
`metadata`	`Record<string, string>`	No	Arbitrary key-value pairs forwarded to your signer.

The destination chainId, address, and token are not static merchant configuration. They are set dynamically per transaction, typically based on the user’s embedded wallet.

Choose destination values from Blink’s active routing catalog. See Supported Networks and Wallets for the current wallet, chain, token, and fee model details.

Minimum deposit

Pass minimumDeposit to requestDeposit, not to the constructor or appearance. The same request property works with the web SDK, mobile SDK, and their React hooks.

await deposit.requestDeposit({
  amount: 50,
  chainId: 8453,
  address: userWalletAddress,
  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC on Base
  minimumDeposit: 10, // USD
});

Blink uses the higher of your minimum and the chosen route’s minimum. For example, passing 2 cannot lower a route minimum of

5. Passing `10` raises it to

10. The Deposit button stays disabled below that amount, and the manual/QR deposit terms show the same minimum. Use a finite number greater than 0 and less than 1,000,000. Values round up to whole cents: 9.991 becomes 10.00. Omit the property or pass null to use Blink’s route minimum. The web SDK logs and ignores invalid values; the mobile SDK rejects them with INVALID_REQUEST. minimumDeposit is unsigned and is not sent to your signer. Enforce any required crediting minimum on your backend as well.

Multiple destinations

If a user can be credited at more than one (chain, token, address) — say USDT on Tron, USDT on Ethereum and USDC on Polygon, each at its own wallet — pass them all:

await deposit.requestDeposit({
  amount: 50,
  destinations: [
    { chainId: 728126428, address: 'TQn9Y2…', token: 'TR7NHq…' }, // USDT on Tron
    { chainId: 1,         address: '0x1a5F…', token: '0xdAC1…' }, // USDT on Ethereum
    { chainId: 137,       address: '0x9bC1…', token: '0x3c49…' }, // USDC on Polygon
  ],
});

Every deposit still settles on one of them. Blink picks the entry from the asset the user sends: a chain-and-token match settles directly with no bridge and no fee; otherwise the same asset on another chain, then the same chain, then anything else, with an Ethereum entry chosen last. Your order breaks ties, so list the destinations you would rather receive first. Tron entries are reachable through the send-to-address flow only. The completed DepositResult.transfer.destinations names the entry that was used. Your signer receives the menu as destinations and must verify ownership of every address in it — see Build Your Signer Endpoint. No two entries may share a chain and token, and destinations replaces chainId/address/token rather than accompanying them.

Deposit result

When the payment completes, the SDK returns a DepositResult:

interface DepositResult {
  transfer: TransferSummary;
  idempotencyKey?: string;
  preview?: {
    amount: number;
    chainId: number;
    address: string;
    token: string;
  };
}

interface TransferSummary {
  id: string;
  status: string;
  amount?: { amount: number; currency: string };
  destinations?: Array<{
    chainId: string;
    address: string;
    token?: { address?: string; symbol?: string };
  }>;
}

Status flow

Status	Meaning
`idle`	No active flow.
`signer-loading`	Calling the merchant signer endpoint.
`iframe-active`	Hosted flow iframe is open, waiting for user to complete payment.
`completed`	Transfer succeeded.
`error`	Something failed.

deposit.on('status-change', (status) => console.log('Status:', status));

deposit.status;    // current status
deposit.result;    // last DepositResult (when completed)
deposit.error;     // last DepositError (when error)
deposit.isActive;  // true during signer-loading or iframe-active

Error handling

See Error Codes for the full reference. Every error is a DepositError with a machine-readable code:

import { DepositError, getDisplayMessage } from '@swype-org/deposit';

try {
  await deposit.requestDeposit({ /* ... */ });
} catch (err) {
  if (err instanceof DepositError) {
    showToast(getDisplayMessage(err));
    console.error(err.code, err.message);
  }
}

Lifecycle

// Close the deposit iframe without waiting for completion
deposit.close();

// Tear down and release all resources (call on unmount / page unload)
deposit.destroy();

Metadata and order reference

Pass merchant-specific data through the flow for reconciliation:

await deposit.requestDeposit({
  amount: 50,
  chainId: 8453,
  address: '0x...',
  token: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
  reference: 'order-123',
  metadata: { invoiceId: 'INV-456', customerId: 'cust-789' },
});

The reference and metadata are forwarded to your signer endpoint so you can correlate the payment with your internal records.

Security

The deposit UI loads live from https://pay.blink.cash. Before going live, lock the iframe origin with a Content-Security-Policy on your page and learn how to verify the build:

Content-Security-Policy: frame-src https://pay.blink.cash; script-src 'self';

See Security & Content Integrity for the full model, including passkey delegation and build-manifest verification.

Mobile browser considerations

Mobile overlay: On phone-sized devices, the transfer uses Blink’s full-screen overlay. A requested embedded presentation also resolves to this overlay so the flow has enough room.
Passkey / WebAuthn: The SDK transparently handles WebAuthn ceremonies between the cross-origin iframe and the parent page. No additional configuration is needed.
callbackScheme: Always pass null (or omit) for browser integrations. Reserved for native app deep-link flows.
Viewport meta tag: Ensure your page includes a proper viewport meta tag:

<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" />

Embedding Blink in an aggregator

​Install

​JavaScript

​React hook

​Prebuilt deposit button

​Configuration

​Full widget vs. one tap

​Dark and light mode

​Automatic detection from your page

​Switching theme at runtime

​What theming does not cover

​Brand colors

​Deposit titles

​Custom signer function

​Deposit request fields

​Minimum deposit

​Multiple destinations

​Deposit result

​Status flow

​Error handling

​Lifecycle

​Metadata and order reference

​Security

​Mobile browser considerations

Install

JavaScript

React hook

Prebuilt deposit button

Configuration

Full widget vs. one tap

Dark and light mode

Automatic detection from your page

Switching theme at runtime

What theming does not cover

Brand colors

Deposit titles

Custom signer function

Deposit request fields

Minimum deposit

Multiple destinations

Deposit result

Status flow

Error handling

Lifecycle

Metadata and order reference

Security

Mobile browser considerations