---
title: "Drop in. Wire up. Transact."
url: "https://platformdocs.coinme.com/#/build"
markdown: "https://platformdocs.coinme.com/pages/build/index.md"
summary: "Web, iOS and Android each get a native SDK that loads the Coinme Widget, runs the bridge handshake and hands you typed events. The configuration you send and the events you receive are identical on all three. Get started in minutes not days."
---

# Drop in. Wire up. Transact.

Web, iOS and Android each get a native SDK that loads the Coinme Widget, runs the bridge handshake and hands you typed events. The configuration you send and the events you receive are identical on all three. Get started in minutes not days.

<a id="sdks"></a>

## Widget SDKs

### Web: An iframe you own.

Framekit. One React component or a plain script. Your page's origin is the trust boundary.

```tsx
<CoinmeFrame
  orchestratorUrl="…"
  config={{ rampId }}
  onEvent={handle} />
```

More: [Web](https://platformdocs.coinme.com/pages/build/web/overview.md)

### iOS: A view controller you present.

CoinmeBridge · Swift. Or embed as a child. One long-lived session; a delegate with four methods.

More: [iOS](https://platformdocs.coinme.com/pages/build/native/ios/overview.md)

### Android: A fragment you host.

CoinmeBridge · Kotlin. Same config, same events, the same session pattern, in Kotlin with a listener.

More: [Android](https://platformdocs.coinme.com/pages/build/native/android/overview.md)

<a id="all"></a>

## The whole library

The Widget SDKs above put the complete ramp in your app. The Risk SDK and the Vault SDK plug Coinme into a ramp you build yourself. Every SDK, on every platform, with all of its documents, lives in one indexed library.

The Library lists 25 SDKs in 7 families:

| Family | SDK | Platform | Package | What it does |
| --- | --- | --- | --- | --- |
| Widget SDK | [Framekit](https://platformdocs.coinme.com/pages/build/web/overview.md) | Web | `@coinme/coinme-bridge-framekit` | The widget in an iframe you own. React component or plain script. |
| Widget SDK | [CoinmeBridge for iOS](https://platformdocs.coinme.com/pages/build/native/ios/overview.md) | iOS | `CoinmeBridge` · Swift | A view controller you present or embed. One long-lived session, a four-method delegate. |
| Widget SDK | [CoinmeBridge for Android](https://platformdocs.coinme.com/pages/build/native/android/overview.md) | Android | `CoinmeBridge` · Kotlin | A fragment you host. Same config, same events, a listener instead of a delegate. |
| Risk SDK | [Risk SDK for Web](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md) | Web | `@coinme-security/risk-sdk-js` | Set up the engine at start, tag flows and elements, fetch a session tag before transacting. |
| Risk SDK | [Risk SDK for iOS](https://platformdocs.coinme.com/docs/risk-sdk-for-ios-native-apps.md) | iOS | `CoinmeRisk` · Swift | Behavioural and device signal from native iOS apps. |
| Risk SDK | [Risk SDK for Android](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md) | Android | `CoinmeRisk` · Kotlin | Behavioural and device signal from native Android apps. |
| Risk SDK | [Risk SDK for React Native](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md) | React Native | `@coinme-security/risk-sdk-react-native` | The web SDK's surface with native device collectors. |
| Vault SDK | [Vault SDK for JavaScript](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md) | Web | `@coinme-security/vault-sdk-js` | Hosted card fields for any web stack. createCoinmeVault, five field factories, submitPaymentMethod. |
| Vault SDK | [Vault SDK for iOS](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md) | iOS | `CoinmeVault` · Swift | Hosted card capture in native iOS. |
| Vault SDK | [Vault SDK for Android](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md) | Android | `CoinmeVault` · Kotlin | Hosted card capture in native Android. |
| Vault SDK | [Vault SDK for React Native](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-react-native.md) | React Native | `@coinme-security/vault-sdk-react-native` | Hosted card capture for React Native apps. |
| Onboarding SDK | [Onboarding SDK for JavaScript & React](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) | Web | `@coinme-security/onboarding-sdk-react` | A drop-in form or headless building blocks that onboard a customer and return their customerId, then verify the customer's phone with a texted code. The SSN is typed into a hosted field. |
| Onboarding SDK | [Onboarding SDK for React Native](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) | React Native | `@coinme-security/onboarding-sdk-react-native` | The drop-in form, headless building blocks and phone verification step for iOS and Android apps built with React Native, Expo included. The SSN is typed into the vault's secure field and never reaches your code. |
| Compliance SDK | [Compliance SDK for JavaScript & React](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) | Web | `@coinme-security/compliance-sdk-react` | Coinme's jurisdictions, rule helpers, localized consent and disclosure copy, and attestations, as a framework-agnostic core with React bindings. |
| Compliance SDK | [Compliance SDK for React Native](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) | React Native | `@coinme-security/compliance-sdk-react-native` | Coinme's jurisdictions, rule helpers, localized consent and disclosure copy, and attestations for iOS and Android apps built with React Native, with the same provider and hooks as the web SDK and native rendering of the copy. |
| CaaS API clients | [Core API client](https://platformdocs.coinme.com/docs/caas-core-api-client.md) | Server | `@coinme/core-api-client` | Authentication with AuthService, supported crypto currencies and their chains, and historical market data. |
| CaaS API clients | [Prove onboarding API client](https://platformdocs.coinme.com/docs/caas-prove-onboarding-api-client.md) | Server | `@coinme/prove-onboarding-api-client` | Phone verification, identity prefill and verification, and customer onboarding. |
| CaaS API clients | [Quotes API client](https://platformdocs.coinme.com/docs/caas-quotes-api-client.md) | Server | `@coinme/quotes-api-client` | Transactional and informational quotes, and transaction limits. |
| CaaS API clients | [Transactions API client](https://platformdocs.coinme.com/docs/caas-transactions-api-client.md) | Server | `@coinme/transactions-api-client` | Buy and sell, with or without a quote, sell all, and the blockchain id of a sell funded from an external wallet. |
| CaaS API clients | [History API client](https://platformdocs.coinme.com/docs/caas-history-api-client.md) | Server | `@coinme/history-api-client` | Asset balances, transaction history and a single transaction. |
| CaaS API clients | [Locations API client](https://platformdocs.coinme.com/docs/caas-locations-api-client.md) | Server | `@coinme/locations-api-client` | The jurisdictions Coinme is licensed in. |
| CaaS API clients | [Send API client](https://platformdocs.coinme.com/docs/caas-send-api-client.md) | Server | `@coinme/send-api-client` | Sending to an external wallet. |
| CaaS API clients | [Custody API client](https://platformdocs.coinme.com/docs/caas-custody-api-client.md) | Server | `@coinme/custody-api-client` | Not yet published. Customer wallets, network fee estimates, sends and your enterprise balances. |
| CaaS API clients | [Cash ramp API client](https://platformdocs.coinme.com/docs/caas-cash-ramp-api-client.md) | Server | `@coinme/cash-ramp-api-client` | Not yet published. Cash locations and order templates. |
| Wallet addresses | [Wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md) | Web | `@coinme/wallet-address-validator` | One typed function that checks a wallet address for 160+ coins and tokens across more than 60 chains, offline and with no dependencies. Runs in browsers, Node.js 18+ and React Native 0.74+ with Hermes. |

Every SDK's documents are listed in the [Library](https://platformdocs.coinme.com/pages/build/library.md).

<a id="bridge"></a>

## How the bridge works, on every platform

Each SDK is a thin host around the Coinme Widget. It loads the URL, proves who it is, sends one configuration object, and then relays events both ways. The five steps below are the same whether the container is an iframe, a WKWebView or an Android WebView.

1. **Load**: The SDK opens the Coinme Widget URL in its container: iframe, WKWebView or WebView. Wire: `orchestratorUrl`
2. **Handshake**: The Coinme Widget says hello; the SDK acknowledges with its identity. Wire: `handshake → handshakeAck`
3. **Configure**: One CoinmeConfig crosses the bridge: identity, theme, transaction pre-fill, locks, where to start, etc. Wire: `host.config`
4. **Ready**: The starting presenter mounts. Your sessionReady fires. Then off to the races. Wire: `bridge.session.ready`
5. **Relay**: Events out, updates in, for as long as the container lives. Wire: `bridge.* events`

- **How the Widget recognises you**: On the web, your site must be on the embed allowlist: send Coinme the hostname of every environment you deploy. In a native app, the **partnerKey** you send in the handshake identifies your app instead.
- **What can change mid-session**: Every config you send reaches the Widget at once, and it merges them. Theme and language take effect immediately. Transaction fields set up a transaction, and a running one only reads them when it initialises: 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 (`restartTransaction` on iOS and Android, `updateConfig` on the web); there is no need to destroy or remount the Widget.

<a id="config"></a>

## One configuration object

Everything the Coinme Widget needs travels in a single `CoinmeConfig`. Field names match across Swift, Kotlin and TypeScript. Filter by group; the shaded fields are the ones that also apply live.

On the page the live fields are shaded; here the "Live via `updateConfig`" column marks them.

| Field | Type | Group | Required | Live via `updateConfig` | What it does |
| --- | --- | --- | --- | --- | --- |
| `rampId` | `string` | Identity | required | no | Your ramp, from onboarding. Selects remote config and attributes transactions. |
| `partnerKey` | `string` | Identity | optional | no | Identifies your app to the Widget in the handshake. Native integrations need it; optional on the web. |
| `environment` | `"dev"\|"stage"\|"prod"` | Identity | optional | no | Has no effect: the Widget ignores it. Leave it unset; the URL you load picks the environment. |
| `rampName` | `string` | Identity | optional | no | Human-readable name, used with rampId for attribution and barcode resumption. |
| `flowId` | `string` | Identity | optional | no | Which flow opens when the session mounts; ignored after that. Defaults to the buy flow. "landing" opens home, where the ramp's initial_flow decides what renders, and "transactionHistory" the transaction history. |
| `theme` | `"light"\|"dark"` | Appearance | optional | yes | Widget colour scheme. Resolve "system" natively first. |
| `language` | `BCP 47` | Appearance | optional | yes | Widget UI language, e.g. "en", "es". |
| `destinationCurrency` | `string` | Transaction | optional | no | Asset ticker to buy, e.g. "BTC", "POL". |
| `destinationCurrencyLock` | `boolean` | Transaction | optional | no | Prevent changing the asset inside the widget. |
| `sourceAmount` | `number` | Transaction | optional | no | Fiat amount to spend. |
| `sourceCurrency` | `string` | Transaction | optional | no | Fiat currency for sourceAmount, e.g. "USD". |
| `sourceAmountLock` | `boolean` | Transaction | optional | no | Prevent editing the amount inside the widget. |
| `paymentMethod` | `"cash"\|"debit"` | Transaction | optional | no | Pre-select a rail. With the lock, narrows the flow to that rail. |
| `paymentMethodLock` | `boolean` | Transaction | optional | no | Prevent changing the payment method. |
| `walletAddress` | `string` | Wallet | optional | no | Pre-fill the destination wallet for the selected asset. |
| `walletAddressLock` | `boolean` | Wallet | optional | no | Prevent editing the destination. Meaningless without walletAddress. |
| `location` | `CoinmeLocation` | Location | optional | no | city / state / zipCode and lat / long. Lets the widget suggest cash locations without asking the WebView for geolocation. |
| `externalSessionId` | `string` | Tracking | optional | no | Your session ID, fixed for the app session. Echoed in Coinme logs. |
| `externalTransactionId` | `string` | Tracking | optional | no | Fresh per purchase attempt. Lines up your logs with ours. |
| `metadata.source` | `string` | Tracking | optional | no | Free-form attribution, e.g. campaign or source tag. |

\* Shaded rows apply to a running session through `updateConfig`. All other fields are read when the flow initialises or restarts. Field list reflects CoinmeBridge 1.1.0.

## Eighteen typed events and a ready signal. Four that 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.

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

<a id="credentials"></a>

## What Coinme gives you

Three values arrive at onboarding, and one thing happens on our side.

- **`rampId`**: Names your integration. Selects the remote configuration the Widget runs with, and attributes every transaction to you.
- **`partnerKey`**: Identifies your app to the Widget in the handshake. Native integrations need it; a wrong or empty value means the session never becomes ready. Keep it in runtime configuration with your rampId. On the web it is optional.
- **`orchestratorUrl`**: The deployment to load. The SDK derives the trusted message origin from it, so it must point straight at the Widget deployment, not through a redirect.
- **On our side**: Web hosts are added to the embed allowlist by hostname. Local development hosts work against the stage Widget without an allowlist entry, so a passing local test does not prove production will embed. Ask for the allowlist entry when you ask for the ramp ID.

**Important:** The URL you load picks the environment: stage-widget.coinme.com for testing, the production URL for production. The `environment` field in the config has no effect; leave it unset.

<a id="agents"></a>

## Build with an agent

Every page here is also published as Markdown for coding agents, with prompts to start from.

- **[Point your agent at the docs](https://platformdocs.coinme.com/pages/build/agents.md)** (Agentic support): Where the machine-readable rendition lives, prompts for each platform, and what the agent will ask you for.

Build summarises the Coinme demo apps. Each platform section goes deeper.

- [Framekit example](https://platformdocs.coinme.com/pages/build/web/overview.md)
- [iOS demo app](https://platformdocs.coinme.com/pages/build/native/ios/overview.md)
- [Android demo app](https://platformdocs.coinme.com/pages/build/native/android/overview.md)
