---
title: "From zero to embedded in six steps."
url: "https://platformdocs.coinme.com/#/build/web/how-to-use"
markdown: "https://platformdocs.coinme.com/pages/build/web/how-to-use.md"
summary: "Everything below is copy-paste ready. If you want the concepts behind it, read How it works; when your embed is up, verify it with the framekit-doctor CLI (see Doctor)."
surface: "ramp"
platform: "web"
package: "@coinme/coinme-bridge-framekit"
version: "1.1.2"
peerDependencies: {"react":">=18.0.0","react-dom":">=18.0.0"}
---

# From zero to embedded in six steps.

Everything below is copy-paste ready. If you want the concepts behind it, read [How it works](https://platformdocs.coinme.com/pages/build/web/how-it-works.md); when your embed is up, verify it with the framekit-doctor CLI (see [Doctor](https://platformdocs.coinme.com/pages/build/web/doctor.md)).

> **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).

## 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);
      }
    }
  }}
/>
```

Your Coinme integration contact can provide the full catalog of event names for your ramp; see the callout below for which events cross the bridge.

## 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 */ />
    </>
  );
};
```

Prefer hooks? This site ships a useCoinmeBridge hook wrapping the same ref with typed senders and event subscriptions.

## 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.

> **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.

## Cue up transactions: recipes

The config is session intent: it overlays the ramp's static configuration without redefining it. Prefill fields to start the user somewhere; add the matching lock to make a field non-negotiable. Each recipe below is a complete config for a common arrangement.

### 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.

## rampConfig reference

Every session-intent property the bridge accepts, from the bridge contract. All of them are exposed on framekit's typed CoinmeConfig, so anything the wire can carry, your code can set.

| 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 |

## 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).
