Choose your integration

There is no single "right" way to embed 0Gate. The same session — created server-side with POST /v1/gate_sessions and rendered in the browser — can power a full buy/sell/swap surface, a single locked flow, a hosted redirect, or a UI you build yourself. What differs is how much of the frontend you hand to 0Bit versus how much you own.

This page is a decision page. Start with the tree, land on a path, copy the teaser, then follow the linked guide.

Decision tree

Answer three questions, in order: do you control the frontend, do you need all three flows (buy + sell + swap) in one surface, and can you render an iframe in your environment?

What every path shares

Whichever leaf you land on, three SDK invariants hold — and they explain why even the "Server API only" path still embeds or redirects for the user-facing leg:

• The browser SDK refuses secret keys. new GateRamp(...) and GateRamp.redirectToCheckout(...) both throw SecretKeyInBrowserError the moment a key matches /^sk_/, and reject anything that isn't pk_test_ / pk_live_ with a ConfigError. There is no way to drive settlement from the browser.
• The pre-flight is POST /v1/embed/bootstrap. Both mount() and the React components call it first with Authorization: Bearer <pk_> (plus clientSecret in the body when present), so a bad key or non-allowlisted origin fails before a blank iframe renders. It returns a 1-hour embed JWT the iframe then sends as X-Embed-Token on its own downstream calls.
• Success is { txId, sessionId? }, not settlement. Every embedded path fires PAYMENT_SUCCESS with { txId, sessionId?, amount?, currency? }. That is a UX signal. Grant value only on the signed gate_session.completed webhook.

1. Full widget

The complete on/off-ramp. One call to GateRamp.mount() renders an iframe with the buy / sell / swap tab strip; 0Bit hosts every screen — quote, KYC, payment method, on-chain settlement.

When to use it

• You want the fastest, most complete integration and are happy to let users choose the flow.
• You control your own page markup and can render an iframe (most web apps).
• You want buy, sell, and swap available from a single surface.

How it works. Your server creates a session (omit flow to keep all tabs). Your page constructs GateRamp with the publishableKey + clientSecret and calls .mount(target, handlers). The SDK pre-flights POST /v1/embed/bootstrap with the pk_, loads the iframe at gate.0bit.app, and resolves the mount promise on WIDGET_READY.

npm install @0bit/gate/browser

import { GateRamp } from '@0bit/gate/browser';

const ramp = new GateRamp({
  publishableKey: 'pk_test_AbCdEfGh1234567890abcdefghijklmn',
  clientSecret: 'gsec_..._...', // from POST /v1/gate_sessions on your server
  environment: 'sandbox',       // -> gate-sandbox.0bit.app
});

await ramp.mount('#ramp', {
  onReady: () => console.log('widget ready'),
  onSuccess: ({ txId, sessionId }) => { /* UX only — wait for the webhook before granting value */ },
  onError: ({ code, message }) => console.warn(code, message),
  onClose: ({ reason }) => console.log('closed:', reason),
});

npm install @0bit/gate/react

import { RampCheckout } from '@0bit/gate/react';

export function Checkout({ clientSecret }: { clientSecret: string }) {
  return (
    <RampCheckout
      publishableKey={import.meta.env.VITE_GATE_PUBLISHABLE_KEY}
      clientSecret={clientSecret}
      environment="sandbox"
      onSuccess={({ txId }) => {/* UX only — webhook is authoritative */}}
      onError={(e) => console.warn(e.code, e.message)}
    />
  );
}

<div id="ramp"></div>
<script src="https://cdn.jsdelivr.net/npm/@0bit/gate/browser"></script>
<script>
  // The IIFE bundle exposes the global GateJS.
  const ramp = new GateJS.GateRamp({
    publishableKey: 'pk_test_...',
    clientSecret: 'gsec_..._...',
    environment: 'sandbox',
  });
  ramp.mount('#ramp', { onSuccess: () => {/* UX only */} });
</script>

Theme it with ramp.setTheme('dark'), or pass theme in the constructor. → 0Gate quickstart walks the full widget end to end.

GateRamp constructor options

Every field on the constructor config, from the SDK source. Only publishableKey is required.

The rendered iframe is fixed at max-width: 440px, centered, allow="payment *", with data-0gate="ramp".

Mount lifecycle and handlers

mount(target, options) accepts a selector string or an HTMLElement (a missing/invalid target throws MountTargetError), and returns a Promise<void> that resolves on WIDGET_READY or rejects after a 15-second timeout if the iframe never signals ready. Calling mount() twice without unmount() throws StateError.

Other instance methods: setTheme('light' \| 'dark'), updateConfig({ amount?, currency?, targetToken?, targetNetwork? }), and unmount() (safe to call when not mounted; tears down the iframe + the message listener). Calls made before mount() or after unmount() are dropped silently rather than thrown.

postMessage protocol

The host SDK and the iframe speak a typed postMessage contract with strict origin + source checks (messages from any origin other than the loaded iframe are ignored). You rarely touch this directly, but it explains the lifecycle:

• host → iframe: INIT_CONFIG (first config push after ready), SET_THEME, UPDATE_CONFIG.
• iframe → host: WIDGET_READY, PAYMENT_SUCCESS, PAYMENT_ERROR, PAYMENT_CLOSE.

MessageType and the isIframeMessage() type-guard are exported from @0bit/gate/browser if you run your own listener.

2. Kit blocks

The same hosted iframe, locked to one flow with the tab strip hidden. Reach for a kit block when the surrounding page already implies the action — a "Top up" button (on-ramp), a "Cash out" screen (off-ramp), or a "Convert" panel (swap).

When to use it

• You want a single flow, not a tab picker — buy or sell or swap.
• You still want 0Bit to host KYC, payments, and settlement (same as the full widget).
• You want the surface to read as part of your own UI, not a generic ramp.

How it works. Identical to the full widget — server-created session, embed bootstrap, iframe — except the flow is pinned. Pin it either by passing flow when you create the session (on_ramp / off_ramp / swap) or by using the matching kit-block factory in the browser. The factories are thin wrappers over GateRamp that set flow for you.

import { createGateOnRamp } from '@0bit/gate/browser';
// also: createGateOffRamp(cfg), createGateSwap(cfg)

const onramp = createGateOnRamp({
  publishableKey: 'pk_test_...',
  clientSecret: 'gsec_..._...',
  environment: 'sandbox',
});

await onramp.mount('#topup', {
  onSuccess: ({ txId }) => { /* UX only — confirm via webhook */ },
});

import { GateOnRamp } from '@0bit/gate/react';
// also: <GateOffRamp />, <GateSwap />

export function TopUp({ clientSecret }: { clientSecret: string }) {
  return (
    <GateOnRamp
      publishableKey={import.meta.env.VITE_GATE_PUBLISHABLE_KEY}
      clientSecret={clientSecret}
      environment="sandbox"
      onSuccess={() => {/* UX only */}}
    />
  );
}

The factories are GateRamp + a pinned flow

Each factory returns a normal GateRamp instance — same constructor options, same mount() lifecycle and handlers as path 1 — with flow already set. The factory config type is GateRampConfig with flow omitted, so you cannot pass a conflicting flow:

Because the return value is a GateRamp, setTheme(), updateConfig(), and unmount() all work identically. The React equivalents (<GateOnRamp />, <GateOffRamp />, <GateSwap />) are <RampCheckout /> with the same flow baked in.

3. Hosted redirect

No iframe at all. GateRamp.redirectToCheckout() sends the user to a full-page 0Bit-hosted checkout and brings them back to the session's return_url. This is the escape hatch for any environment where embedding fails.

When to use it

• The page can't render an iframe — a mobile WebView, a strict / hostile Content-Security-Policy, an <iframe>-stripping CMS, or an email/link surface.
• You have no real frontend to mount into (no-code builders, marketing pages).
• You'd rather not manage iframe lifecycle and prefer a clean full-page handoff.

How it works. Your server still creates the session — clientSecret is required here, hosted mode is always session-bound and anonymous access is disabled. The redirect drops the user on the hosted checkout; on completion they return to return_url. There is no onSuccess callback in this mode, so the webhook (and the return_url arrival) is your only completion signal.

import { GateRamp } from '@0bit/gate/browser';

// Full-page navigation — no element to mount into.
GateRamp.redirectToCheckout({
  publishableKey: 'pk_test_...',
  clientSecret: 'gsec_..._...', // REQUIRED — hosted mode is session-bound
  environment: 'sandbox',
  theme: 'dark',
});

<!-- Trigger the redirect from a button when you ship the SDK on the page. -->
<button id="buy">Buy crypto</button>
<script src="https://cdn.jsdelivr.net/npm/@0bit/gate/browser"></script>
<script>
  document.getElementById('buy').addEventListener('click', () => {
    GateJS.GateRamp.redirectToCheckout({
      publishableKey: 'pk_test_...',
      clientSecret: 'gsec_..._...',
      environment: 'sandbox',
    });
  });
</script>

redirectToCheckout signature

It is a static method — no instance, no mount(), no DOM target — and it returns void (the page unloads as window.location.assign(...) fires). It validates input and throws before navigating:

It builds the URL by appending client_secret, publishableKey, and (optional) theme query params onto the resolved iframe origin, then navigates. Unlike mount(), it does not call /v1/embed/bootstrap from the host — the hosted page performs the bootstrap itself.

4. Server API only

The advanced path: skip the SDK widget entirely, call the REST API from your server, and build your own UI against the session lifecycle. You take on more — quote display, status polling, error states, and routing the user into KYC when an event demands it — in exchange for total control of the experience.

When to use it

• You need a fully custom, branded flow that an iframe can't deliver.
• You're integrating into a non-web surface, a backend job, or your own native client.
• You accept owning the status / error / KYC UX that the widget would otherwise handle.

How it works. Create a session, retrieve it to track status, drive your own UI off the lifecycle, and cancel if the user backs out. Use a server SDK or raw HTTP — both hit the same routes. Auth is Authorization: Bearer <sk_...>; the SDKs add the Idempotency-Key on writes automatically (send your own uuid v4 if you call the API directly).

# Create
curl -X POST https://gate-api-sandbox.0bit.app/v1/gate_sessions \
  -H "Authorization: Bearer $GATE_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "amount": "100.00",
    "currency": "EUR",
    "return_url": "https://yourapp.example/checkout/done"
  }'

# Retrieve status
curl https://gate-api-sandbox.0bit.app/v1/gate_sessions/{id} \
  -H "Authorization: Bearer $GATE_KEY"

# Cancel
curl -X POST https://gate-api-sandbox.0bit.app/v1/gate_sessions/{id}/cancel \
  -H "Authorization: Bearer $GATE_KEY"

npm install @0bit/gate

import { GateClient } from '@0bit/gate';

const client = new GateClient({
  apiKey: process.env.GATE_KEY!,            // sk_... — server only
  baseUrl: 'https://gate-api-sandbox.0bit.app', // SDK origin; resource paths append /v1
});

const session = await client.sessions.create({
  amount: '100.00',
  currency: 'EUR',
  return_url: 'https://yourapp.example/checkout/done',
});

const current = await client.sessions.retrieve(session.id);
// await client.sessions.cancel(session.id);

// Build your own UI off session.status; confirm settlement via webhook.

pip install 0bit-gate

import os
from zerobit.gate import GateClient  # PyPI dist is "0bit-gate"

client = GateClient(
    api_key=os.environ["GATE_KEY"],            # sk_... — server only
    base_url="https://gate-api-sandbox.0bit.app", # SDK origin; resource paths append /v1
)

session = client.sessions.create({
    "amount": "100.00",
    "currency": "EUR",
    "return_url": "https://yourapp.example/checkout/done",
})

current = client.sessions.retrieve(session["id"])
# client.sessions.cancel(session["id"])

Endpoints and rate limits

The whole user-facing leg runs on four routes. The widget paths call them for you; here you call them yourself.

Create-session parameters

client.sessions.create(params) body, from the SDK types. Required: amount, currency, return_url.

The response is a GateSession (id, object: 'session', status, expires_at, created_at, metadata, …) plus a one-time client_secret shaped gsec_<id>_<rand>, returned only on create — later reads omit it.

Error handling

Both server SDKs throw a typed hierarchy (mirrored across Node and Python) so you can instanceof or branch on .code. The HTTP status maps to a concrete subclass:

Every GateError carries statusCode?, code, requestId? (the echoed Request-Id — quote it in support tickets), and raw?. The HTTP client auto-retries 408 / 425 / 429 / 500 / 502 / 503 / 504 and connection/timeout failures (2 retries, exponential backoff with jitter, honoring Retry-After) — so the errors you actually catch are the non-retryable ones.

React components

@0bit/gate/react wraps the same iframe and protocol declaratively. <RampCheckout /> (also exported as <GateCheckout />) is the full widget; <GateOnRamp />, <GateOffRamp />, <GateSwap /> are the flow-locked blocks (each is <RampCheckout /> with flow pinned). The package re-exports the whole @0bit/gate/browser error + type surface, so you don't install both.

Props

RampCheckoutProps is the GateRampConfig (minus fetchImpl) plus handlers and container styling:

onMountError(err) is React-specific — it fires when the constructor throws (e.g. an sk_ key) or the mount() promise rejects (bootstrap failure, ready timeout). The other handlers carry the same payloads as the imperative SDK.

Re-mount semantics

The component lists every identity prop in its mount effect, so changing any of them re-mounts a fresh iframe with the new config — exactly what you want for "a different checkout." Re-renders that only swap handler closures do not re-mount: handlers are read through a pinned ref. On unmount it calls ramp.unmount() and clears the instance.

import { GateOnRamp } from '@0bit/gate/react';

<GateOnRamp
  publishableKey={import.meta.env.VITE_GATE_PUBLISHABLE_KEY}
  clientSecret={clientSecret}
  environment="sandbox"
  onSuccess={({ txId }) => router.push('/done')}
  onMountError={(err) => console.error('could not mount', err)}
/>

Comparison at a glance

Next steps