Examples

Static playground (live demo)

examples/playground is a Vite page. The server runs in the browser with mock providers, so it needs no backend and no secrets. The docs site hosts it. See Live demo (playground).

Next.js playground

examples/next-demo is a Next.js App Router app with a playground. You pick the flow (deposit or withdraw), the user's country, the destination, who holds the funds, the wallet, the theme and the accent color, and the widget restarts with a new session. The page also shows the widget events and the webhooks your backend received.

Run these commands from the root of a clone of the repository:

pnpm install
pnpm build         # the examples import the built packages (dist)
cp examples/next-demo/.env.example examples/next-demo/.env.local
pnpm dev:example   # http://localhost:3000

Variable	Default	Description
OPENRAMP_SECRET	a dev value	32+ characters
PUBLIC_URL	http://localhost:3000	Used for baseUrl and the webhook URL
OPENRAMP_MOCK	1	1: mock providers only, works offline. 0: real Relay for wallet and transfer, mock fiat.
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID	empty	Only browser wallets work without it
OPENRAMP_WEBHOOK_SECRET	a dev value	Signs the webhooks to /api/hooks. A Standard Webhooks secret (whsec_..., from generateWebhookSecret()). Not in .env.example: add it for a real deployment.
XENDIT_SECRET_KEY, XENDIT_WEBHOOK_TOKEN	empty	Adds real Xendit merchant pay-in when both are set
CRON_SECRET	empty	Protects /api/cron. In production, the route refuses all calls when it is not set.
RELAY_API_KEY	empty	Relay API key, for OPENRAMP_MOCK=0. Relay requires it for quotes under its announced policy from 2 Oct 2026; some requests without a key may still work today, but Relay can refuse them at any time. Also needed for deposit address status (/requests/v2 retires on 2026-11-24).
OPENRAMP_ADMIN_TOKEN	empty	32+ characters. Turns on the admin tools and the ops dashboard at /api/openramp/admin.

What to look at:

File	Shows
lib/openramp.ts	createOpenRamp with mock (including offramp: true), Relay and Xendit adapters, webhooks, and the withdraw hooks screenAddress and treasury
app/api/openramp/[...path]/route.ts	Mounting the handler with nextHandlers()
app/api/deposit-session/route.ts	Creating a session in your backend
app/api/withdraw-session/route.ts	Creating a withdraw session with source, custody and allowedDestinations
app/api/cron/route.ts, vercel.json	The background sweep as a Vercel Cron Job, checked with CRON_SECRET
app/api/hooks/route.ts	Verifying webhooks with openramp.webhooks.verify
components/Playground.tsx	OpenRampProvider, DepositButton, WithdrawButton, OpenRampEmbedded, themes, createMockWallet, wagmiWallet
e2e/deposit.spec.ts, e2e/withdraw.spec.ts	Playwright flows on desktop, Android and iPhone
e2e/screens.spec.ts	Screenshot capture

Flows to try:

Setup	Flow
Vietnam, Token on Monad	VietQR, then a mock bridge hop: a two-leg pathway
Singapore, USDC on Base	Card by a popup-safe redirect to a hosted checkout
United States, mock wallet	Pay with wallet (WALLET_TX)
Germany, no wallet	Transfer crypto to a deposit address
Indonesia, Merchant fiat account	QRIS pay-in, no crypto
Philippines, embedded off	Modal mode; a bottom sheet on phones
Withdraw, United States, mock wallet	To wallet: USDC on Base to an Arbitrum address
Withdraw, Philippines, mock wallet	To cash: a GCash payout through the mock offramp
Withdraw, app holds the funds	The demo treasury sends instead of the wallet

Pay from wallet	Confirm in wallet	Transfer: pick a source	Deposit address

Card redirect	Mock hosted checkout	Processing	Crypto methods

Nuxt (Vue)

examples/nuxt-demo is a minimal Nuxt 4 app with @openrampkit/vue. It has the server, a session route and a deposit button, with mock providers only.

pnpm install && pnpm build   # from the repository root, once
pnpm --filter nuxt-demo dev  # http://localhost:3000

File	Shows
server/utils/openramp.ts	createOpenRamp with the mock adapter
server/api/openramp/[...path].ts	Mounting the handler with openramp.handle(toWebRequest(event))
server/api/deposit-session.post.ts	Creating a session in your backend
app/app.vue	OpenRampProvider and DepositButton

SvelteKit (Svelte)

examples/sveltekit-demo is a minimal SvelteKit 3 app (Svelte 5) with @openrampkit/svelte. It has the server, a session route and a deposit button, with mock providers only.

pnpm install && pnpm build        # from the repository root, once
pnpm --filter sveltekit-demo dev  # http://localhost:3000

File	Shows
src/lib/server/openramp.ts	createOpenRamp with the mock adapter
src/routes/api/openramp/[...path]/+server.ts	Mounting the handler with openramp.handle(request)
src/routes/api/deposit-session/+server.ts	Creating a session in your backend
src/routes/+page.svelte	setOpenRamp and use:depositButton

SolidStart (Solid)

examples/solidstart-demo is a minimal SolidStart 2 app with @openrampkit/solid. It has the server, a session route and a deposit button, with mock providers only. SolidStart 2 needs Node.js 24 or later.

pnpm install && pnpm build         # from the repository root, once
pnpm --filter solidstart-demo dev  # http://localhost:3000

File	Shows
src/lib/openramp.server.ts	createOpenRamp with the mock adapter
src/routes/api/openramp/[...path].ts	Mounting the handler with openramp.handle(event.request)
src/routes/api/deposit-session.ts	Creating a session in your backend
src/routes/index.tsx	OpenRampProvider and DepositButton

Cloudflare Worker

examples/cloudflare-worker runs the server as a standalone Worker with a Durable Object session store (durableObjectStore). Your app backend creates sessions over HTTP with a shared API key, through the authorize hook. See Deploy on Cloudflare Workers.

pnpm install && pnpm build   # from the repository root, once
cd examples/cloudflare-worker
cp .dev.vars.example .dev.vars
pnpm dev   # wrangler dev on http://localhost:8787

curl -X POST http://localhost:8787/sessions -H 'x-app-key: dev-app-key' -H 'content-type: application/json' \
  -d '{"userId":"u1","country":"VN","destination":{"type":"crypto","chain":"eip155:8453","token":"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913","address":"0x000000000000000000000000000000000000beef"}}'

Web component demo

packages/web has a Vite demo of the bare element (pnpm --filter @openrampkit/web demo).

Agent (MCP)

examples/agent shows an AI agent that funds a wallet through @openrampkit/mcp. A script calls the MCP tools like an agent. It creates a deposit session, shows the pay link, and waits until the payment completes. The README has the Claude Desktop and Claude Code config. See Agents (MCP).

pnpm build
node examples/agent/agent.mjs           # a script plays the person
node examples/agent/agent.mjs --serve   # you open the pay link in a browser