---
name: coinme-widget-web
description: "Embed the Coinme Widget in a web app with @coinme/coinme-bridge-framekit: install from the private registry, mount CoinmeFrame (React) or createCoinmeFrame (plain script), handle typed events, change settings live, and verify with the Doctor checks. Use when asked to add, embed, integrate or scaffold the Coinme widget on a website or web app."
metadata:
  surface: "ramp"
  package: "@coinme/coinme-bridge-framekit"
  version: "1.1.2"
  peerDependencies: "react >=18.0.0, react-dom >=18.0.0"
---

# Coinme Widget on the web with framekit

## When to use this skill

The human wants the Coinme Widget inside a web page or web app, in React or plain JavaScript. For a native iOS or Android app use the CoinmeBridge skills instead.

## Which integration this is

This skill is for the **Widget / Ramp integration**: the partner embeds the Coinme Widget, and its end users become Coinme customers inside it, where sign-in, KYC, payment and receipts happen. It needs none of the Onboarding, Vault or Risk SDKs. If the human's users are to stay the human's own customers, in the human's own screens, this is the wrong skill: read [Two ways to build on Coinme](https://platformdocs.coinme.com/agents/surfaces.md) and pick a Coinme-as-a-Service skill.

## What you will produce

A page that mounts the widget in an iframe the host owns, configured with the ramp the human was issued, receiving the widget's typed events, with the Doctor checks passing.

## Before you start: ask the human for these

The documentation does not contain them and you cannot derive them. Stop and ask, then continue. Never write a real value into a tracked file; keep each where the row says.

| Value | What it is | Where it goes |
| --- | --- | --- |
| `COINME_REGISTRY_TOKEN` | Read-only token for the private npm registry that serves @coinme/coinme-bridge-framekit. | A gitignored `.env.yarn` (Yarn) or `.npmrc` entry; CI reads it from a secret. |
| `rampId` | The Ramp the widget loads, issued at onboarding with its environment. | Runtime configuration, not source. A placeholder such as `your-ramp-id` must never ship. |
| `partnerKey` | Identifies your app to the Widget in the handshake; needed only when the same integration also runs inside native WebViews. | Runtime configuration, not source. |

## Rules for this skill

- Follow the steps in order and keep the code as written; change only identifiers the human gives you and the places marked as yours.
- Do not invent configuration fields, event names or API methods. What exists is what this skill shows plus what the installed package declares in its type definitions; check those before adding anything.
- Samples show `'your-ramp-id'` and the stage URL as literals so each stays self-contained. In the project, read both from the runtime configuration the human's build uses (for Vite, `VITE_*` variables in a gitignored `.env.local` with a committed `.env.example`), and never commit a real ramp id.
- When a step needs a value you do not have, ask; do not substitute a placeholder that could ship.
- Read the linked pages when a step is unclear; they are the source this skill was generated from.

## Read first

> **Required: your hostname must be allowlisted**
>
> **Your integration will not work until Coinme adds your site's hostname to the embed allowlist.** The widget does not render inside a host it does not recognize, and the bridge handshake never completes. Local development hosts work against the stage Widget without an allowlist entry, which is why an integration that works on your machine can still fail on your deployed site. Before you deploy anywhere, send Coinme the hostname of every environment (e.g. `app.yourcompany.com`, hostname only, no `https://`, no port).

## Procedure

### 1. Install the SDK

Framekit lives on Coinme’s private npm registry, so the only setup beyond a normal install is one auth token. Ask your Coinme integration contact for a read-only entitlement token.

```bash
# 1. Put your Coinme registry token in a file named .env.yarn
#    at the repo root (gitignore it; never commit the real token):
COINME_REGISTRY_TOKEN=<token from your Coinme integration contact>

# 2. Tell your package manager where @coinme packages live (.yarnrc.yml):
npmScopes:
  coinme:
    npmAlwaysAuth: true
    npmAuthToken: '${COINME_REGISTRY_TOKEN}'
    npmRegistryServer: 'https://npm.coinme.com/coinme-sdk-frontend/'

# 3. Install the SDK:
yarn add @coinme/coinme-bridge-framekit
```

npm/pnpm users: the same three settings go in .npmrc: scope registry plus an _authToken for npm.coinme.com.

### 2. Put the widget on a page

One component, one required config field. This is the entire integration; the widget handles auth, KYC, payments, and receipts inside the frame.

```tsx
import { CoinmeFrame } from '@coinme/coinme-bridge-framekit/react';

export const BuyCrypto = () => (
  <div style={{ width: 390, height: 720 }}>
    <CoinmeFrame
      orchestratorUrl="https://stage-widget.coinme.com"
      config={{
        rampId: 'your-ramp-id', // issued by Coinme
      }}
      onSessionReady={() => console.log('Coinme widget is live')}
      style={{ width: '100%', height: '100%' }}
    />
  </div>
);
```

Size the wrapper however you like; the widget fills it. 390×720 is a comfortable minimum.

### 3. React to what happens

The widget reports outcomes as events. The common outcomes arrive pre-typed. Which ones your app handles depends on the features your ramp offers: a card purchase ends with transactionComplete, a cash purchase with barcodeGenerated, and closeRequested is the widget asking to be dismissed. Everything else still arrives, untyped (next step).

```tsx
<CoinmeFrame
  // ...same props as above, plus:
  onEvent={(event) => {
    if (event.type === 'transactionComplete') {
      showThankYouScreen();
    }
    if (event.type === 'userCancelled') {
      returnToStore();
    }
    if (event.type === 'transactionRejected') {
      // The ramp rejected the transaction under a locked config and the
      // widget has signed the user out. The frame and the bridge stay up:
      // tell the user, or send a new config (payload carries asset +
      // transactionType). How you respond is yours to decide.
      explainRejection(event.payload);
    }
  }}
  onError={(error) => console.error('bridge error:', error.kind)}
/>
```

The typed set: transactionComplete, transactionFailed, transactionRejected, userCancelled, kycRequired, kycCompleted, sessionEnded, authStateChanged, backAvailabilityChanged, barcodeGenerated, barcodeInvalidated, redirectRequested, closeRequested, supportRequested, signOutRequested, transactionRestarted, sheetOpened, sheetClosed. Anything not on that list comes through as type "unknown". Every variant carries the full event payload.

### 4. Capture events beyond the typed set

Framekit never drops an event it does not recognize; it arrives as type "unknown" with the original event name and payload intact. That lets you consume flow-specific events without waiting for SDK support.

```tsx
<CoinmeFrame
  // ...same props as above, plus:
  onEvent={(event) => {
    if (event.type === 'unknown') {
      // Framekit passes the original event name and payload through
      // untouched, so you can react to flow-specific events directly
      // (the name below is an example; use one from your ramp's catalog):
      if (event.eventType === 'example.flow.event') {
        trackFlowEvent(event.payload);
      }
    }
  }}
/>
```

### 5. Change settings live

Grab a ref to send config into the running widget without reloading anything. Every update reaches the widget at once. Theme and language change on the spot. Transaction fields (amounts, asset, payment method, wallet and their locks) set up the next transaction: don't change them while the user is in the middle of one, where they can disrupt the user or be ignored. To start the next transaction once one completes, send its fields with updateConfig; there is no need to destroy or remount the frame.

```tsx
import { useRef } from 'react';
import {
  CoinmeFrame,
  type CoinmeFrameRefHandle,
} from '@coinme/coinme-bridge-framekit/react';

export const BuyCrypto = () => {
  const frameRef = useRef<CoinmeFrameRefHandle>(null);

  // From any button, effect, or handler. No reload, no remount:
  const goDark = () => frameRef.current?.updateConfig({ theme: 'dark' });

  return (
    <>
      <button onClick={goDark}>Dark theme</button>
      <CoinmeFrame ref={frameRef} /* ...same props as above */ />
    </>
  );
};
```

### 6. Not using React?

The React component is a thin wrapper. The vanilla factory does everything with zero framework dependencies.

```ts
import { createCoinmeFrame } from '@coinme/coinme-bridge-framekit';

const frame = createCoinmeFrame({
  container: '#coinme',   // any element or CSS selector on your page
  orchestratorUrl: 'https://stage-widget.coinme.com',
  config: { rampId: 'your-ramp-id' },
  onSessionReady: () => console.log('Coinme widget is live'),
});

// The same powers, without React:
frame.updateConfig({ theme: 'dark' });
frame.destroy();
```

Works with any framework or none; the only requirement is a DOM element to mount into.

Notes on step 1. Yarn 4 loads `.env.yarn` on its own and `npmScopes` is Yarn 2+ syntax; set `nodeLinker: node-modules` in `.yarnrc.yml` unless the project already uses Plug'n'Play. With npm or pnpm, put the equivalent in `.npmrc` and export the token in the shell before installing:

```properties
@coinme:registry=https://npm.coinme.com/coinme-sdk-frontend/
//npm.coinme.com/coinme-sdk-frontend/:_authToken=${COINME_REGISTRY_TOKEN}
//npm.coinme.com/coinme-sdk-frontend/:always-auth=true
```

The handlers in step 3 (`showThankYouScreen`, `explainRejection` and so on) stand for the host app's own functions; write the ones the human's app needs. `CoinmeConfig`, `CoinmeEvent` and `CoinmeFrameRefHandle` (the type of a `<CoinmeFrame>` ref) are exported as types from `@coinme/coinme-bridge-framekit/react`.

## Events that most often need an answer

Every SDK delivers the same set with the same payload envelope, plus an `unknown` case carrying the raw wire name for anything newer than your SDK. Which ones your app handles depends on the features your Ramp offers. These four most often change what your app does next.

| Event | What it means for your app |
| --- | --- |
| `sessionReady` | Handshake done, flow mounted. Hide your spinner. |
| `transactionRejected` | The ramp refused the locked asset or type, and the user is already signed out. What happens next is your call: close the panel, or send a new config. |
| `closeRequested` | The widget's own Done. Dismiss it. |
| `barcodeGenerated` | A cash order exists. Store `orderTemplateId` so the user can resume it. |

## Which events cross the bridge

> **Which events cross the bridge**
>
> Which events reach your app depends on your ramp's configuration. Transaction completion, the barcode lifecycle, KYC, sign-out and support requests arrive by default; Coinme enables other flow events for your ramp on request. Coinme can also rename an event to the message name your app expects, or combine several events into one message your app consumes.

## Recipes

Configurations for the common cases. Use one as the starting config and change only what the human asks for.

### Cash purchase: $30 of BTC to a fixed wallet

```ts
// $30 cash purchase of BTC delivered to a specific wallet.
// The method, asset, amount and wallet are locked; the user completes the rest.
const config: CoinmeConfig = {
  rampId: 'your-ramp-id',
  paymentMethod: 'cash',
  paymentMethodLock: true,
  sourceAmount: 30,
  destinationCurrency: 'BTC',
  walletAddress: '<destination wallet address>',
  sourceAmountLock: true,
  destinationCurrencyLock: true,
  walletAddressLock: true,
};
```

### Debit purchase: $70 of ETH, fully pinned

```ts
// $70 debit purchase of ETH. Asset, method, amount AND wallet are locked:
// the user can only review and confirm.
const config: CoinmeConfig = {
  rampId: 'your-ramp-id',
  paymentMethod: 'debit',
  paymentMethodLock: true,
  sourceAmount: 70,
  destinationCurrency: 'ETH',
  walletAddress: '<destination wallet address>',
  sourceAmountLock: true,
  destinationCurrencyLock: true,
  walletAddressLock: true,
};
```

### Cash purchase with the method left open

```ts
// $30 purchase of BTC with asset and amount locked, but the method
// deliberately NOT locked: cash is preselected, yet the user may still
// switch to debit at checkout.
const config: CoinmeConfig = {
  rampId: 'your-ramp-id',
  paymentMethod: 'cash',
  sourceAmount: 30,
  destinationCurrency: 'BTC',
  walletAddress: '<destination wallet address>',
  sourceAmountLock: true,
  destinationCurrencyLock: true,
};
```

### Debit purchase with everything editable

```ts
// $50 debit purchase of LINK as a starting point only: nothing is
// locked, so every field is a prefill the user can change.
const config: CoinmeConfig = {
  rampId: 'your-ramp-id',
  paymentMethod: 'debit',
  sourceAmount: 50,
  destinationCurrency: 'LINK',
  walletAddress: '<destination wallet address>',
};
```

### Target a specific ramp by id and name

```ts
// Run a specific ramp experience. rampId selects the configuration;
// rampName carries the human-readable identity for attribution.
const config: CoinmeConfig = {
  rampId: '<your ramp id>',
  rampName: '<your ramp name>',
};
```

> **Lock the asset? Handle transactionRejected**
>
> Recipes that lock `destinationCurrency` can trigger the **transactionRejected** event: if the ramp rejects the locked asset or transaction type, the Orchestrator emits it and **signs the user out**. The frame and the bridge stay up, so there is nothing to remount. How you respond is up to your app: tell the user what happened, or send a new config through `updateConfig` with a different asset or an unlocked field. The payload carries `asset` and `transactionType` so you know what was rejected.

## Configuration reference

| Property | Purpose |
| --- | --- |
| `rampId / rampName` | Which ramp experience to run, and its display name |
| `partnerKey / partnerId` | Identify your app to the Widget in the handshake; native integrations need partnerKey |
| `environment` | Has no effect: the Widget ignores it. Leave it unset; orchestratorUrl picks the environment |
| `flowId` | Which flow opens at mount; ignored after that. Defaults to the buy flow; 'landing' opens home and 'transactionHistory' the transaction history |
| `allowsCamera / allowsLocation / allowsClipboard` | Permissions framekit grants the iframe through its allow attribute; all default to true, and KYC needs the camera |
| `allowsCapture` | No effect on the web. Set to false to block screen capture in the native SDKs |
| `sourceAmount / sourceCurrency` | Prefill the fiat side of the transaction |
| `sourceAmountLock / sourceCurrencyLock` | Freeze the fiat amount / currency |
| `destinationCurrency / destinationCurrencyLock` | Prefill / freeze the crypto asset |
| `destinationAmount / destinationAmountLock` | Prefill / freeze the crypto-side amount |
| `paymentMethod / paymentMethodLock` | Preselect / freeze the method (cash, debit) |
| `walletAddress` | Destination wallet |
| `walletAddressLock` | Freeze the wallet (wire name: walletLock) |
| `walletMemo` | Memo / tag for assets that require one |
| `location { lat, long, city, state, streetAddress, countryCode, zipCode }` | Location prefill, one nested object on CoinmeConfig; framekit flattens it into the payload |
| `externalSessionId / externalTransactionId` | Correlate the session / a specific transaction with your systems |
| `redirectUrl / redirectUrlButtonLabel` | Post-success redirect and its button text |
| `theme / language` | Widget appearance and locale |
| `metadata (source, campaign, referralCode, deviceType)` | Free-form attribution bag |

## Verify

The package ships a CLI. Run the static check from the project root first; it looks for these:

- The SDK is installed and the @coinme registry is configured
- CoinmeFrame / createCoinmeFrame is actually mounted somewhere
- Credentials are real, not placeholders (demo-ramp, your-ramp-id, ...)
- The Orchestrator URL uses HTTPS (or loopback for local dev)
- Foot-guns: hand-rolled iframe sandbox attributes, Referrer-Policy: no-referrer, CSP metas that block the widget

```bash
# From your project root (the SDK ships the CLI):
yarn framekit-doctor check .

# Or without installing anything first:
npx -p @coinme/coinme-bridge-framekit framekit-doctor check .
```

Then run the app and confirm the widget renders and the session-ready callback fires. Once the integration is deployed, probe it; the probe loads the page in a browser and checks the iframe, the CSP, the referrer policy and the bridge session.

```bash
# One-time: the probe drives your locally installed Chrome
yarn add -D playwright-core

# Point it at any deployed (or local) integration:
yarn framekit-doctor probe https://your-deployed-host.example

# Useful flags:
#   --orchestrator <origin>   pin a non-standard widget origin
#   --timeout <ms>            wait budget (default 15000)
#   --json                    machine-readable output for CI
```

### Reading the result

**Done when:** The Doctor checks pass, the widget renders, and the session-ready event arrives.

**Stop and ask the human when** the Ramp ID or environment is refused, or the Doctor reports a host the human must register with Coinme.

Judge every Coinme call by its body, not its HTTP status: a refused request usually comes back as HTTP 200 with the error in the body. [Reading results](https://platformdocs.coinme.com/agents/results.md) has the rule, what each common error code asks you to do, and what to send your Coinme integration contact when something fails.

## Before you ship

- Swap the placeholder rampId for the real value Coinme issued you. Add partnerKey only if the same integration also ships inside native WebViews.
- Give Coinme your production hostname so it can be added to the Orchestrator embed allowlist (hostnames only, no scheme or port).
- If your site sets a Content-Security-Policy, add the widget origin to frame-src.
- Do not send Referrer-Policy: no-referrer; the Widget needs it to recognise your site.
- Point orchestratorUrl at https://widget.coinme.com for production (stage-widget is for testing).

## Reference
- [On the web: overview, with the live embed](https://platformdocs.coinme.com/pages/build/web/overview.md)
- [How it works](https://platformdocs.coinme.com/pages/build/web/how-it-works.md)
- [How to use](https://platformdocs.coinme.com/pages/build/web/how-to-use.md)
- [Doctor](https://platformdocs.coinme.com/pages/build/web/doctor.md)
- [Build: the bridge, configuration fields and events](https://platformdocs.coinme.com/pages/build/index.md)
