---
title: "Agent primer: the Coinme App Platform"
url: "https://platformdocs.coinme.com/agents/primer.md"
markdown: "https://platformdocs.coinme.com/agents/primer.md"
summary: "Orientation for a coding agent new to Coinme: what the Coinme App Platform is, which of its two surfaces and which SDKs apply, the vocabulary the site uses, what an integrator touches versus internal architecture, what is shipped today, and which page answers which kind of question."
---
# Agent primer: the Coinme App Platform
## What the Coinme App Platform is
The Coinme App Platform is how other companies put regulated crypto buying, selling and moving inside their own products. Coinme is the licensed money transmitter and carries the licences, compliance and reporting.
There are two ways to build on it. In the **Widget / Ramp** integration a transactional partner embeds the Coinme Widget, a complete crypto application (a Ramp) that Coinme composes from reusable flows; the transaction is the partner's and the end user is onboarded as a Coinme customer inside the widget. In the **Coinme-as-a-Service (CaaS)** integration a partner with its own users composes Coinme services into its own app with the Onboarding, Compliance, Vault and Risk SDKs, and its backend calls the CaaS API, directly or through the CaaS API clients, server-side convenience wrappers for Node.js; the users stay the partner's customers.
What a Ramp offers is configuration, not code: it resolves at session start from the Ramp's remote configuration (keyed by its Ramp ID), the compliance rules of the user's region, and the session intent the partner sends.
## Which surface, which SDKs
- **Will the end users become Coinme customers, with Coinme's app doing sign-in, KYC and payment?** Then it is a Widget / Ramp integration ([details](https://platformdocs.coinme.com/agents/surfaces.md#ramp)):
- On a website: Framekit, `@coinme/coinme-bridge-framekit`. Skill: [coinme-widget-web](https://platformdocs.coinme.com/skills/coinme-widget-web/SKILL.md).
- In an iOS app: CoinmeBridge for iOS. Skill: [coinme-widget-ios](https://platformdocs.coinme.com/skills/coinme-widget-ios/SKILL.md).
- In an Android app: CoinmeBridge for Android. Skill: [coinme-widget-android](https://platformdocs.coinme.com/skills/coinme-widget-android/SKILL.md).
- Backend only, no front-end channel: the Bridge Proxy. It is described in [the bridge explainer](https://platformdocs.coinme.com/pages/explainers/bridges.md); its build guide is not on this site.
- You do not need the Onboarding, Vault or Risk SDK for the widget itself.
- **Will the users stay your customers, in your own app and UI?** Then it is a CaaS integration ([details](https://platformdocs.coinme.com/agents/surfaces.md#caas)), and you pick the services you need:
- To onboard a customer, run non-documentary KYC and verify their phone afterwards: the Onboarding SDK (`@coinme-security/onboarding-sdk-react` for React and JavaScript web apps, `@coinme-security/onboarding-sdk-react-native` for React Native and Expo apps). Skills: [coinme-onboarding-react](https://platformdocs.coinme.com/skills/coinme-onboarding-react/SKILL.md) and [coinme-onboarding-react-native](https://platformdocs.coinme.com/skills/coinme-onboarding-react-native/SKILL.md).
- To apply Coinme's regional compliance rules in your own screens (which states to offer, what a region excludes, which consents and disclosures to show, and recording what the customer accepted): the Compliance SDK, `@coinme-security/compliance-sdk-react`, for React and JavaScript web apps. Its release on this site is 1.1.3, in **beta** (published and installable, not generally available), and it is **advisory**: Coinme's backend still enforces every rule. Skill: [coinme-compliance-react](https://platformdocs.coinme.com/skills/coinme-compliance-react/SKILL.md). For React Native and Expo apps, `@coinme-security/compliance-sdk-react-native` is also in **beta** (release 1.0.2), with the same rules, provider and hooks; skill: [coinme-compliance-react-native](https://platformdocs.coinme.com/skills/coinme-compliance-react-native/SKILL.md). Every page in [llms-compliance.txt](https://platformdocs.coinme.com/llms-compliance.txt).
- To capture card details without them touching your code: the Vault SDK (JavaScript, iOS, Android, React Native). Skills: [skills/index.json](https://platformdocs.coinme.com/skills/index.json), names `coinme-vault-*`.
- To send the device and behavioural signals Coinme requires before transactional calls: the Risk SDK (web, iOS, Android, React Native). Skills: names `coinme-risk-*` in the same index.
- To call the CaaS API (quotes, buy and sell, history, sends, onboarding and payment methods): the CaaS API clients, `@coinme/*-api-client`. They are **server-side convenience wrappers** over the CaaS REST API, for your Node.js 20+ backend only: `AuthService` holds your partner ID and client secret, so your web and mobile front ends call your backend, never CaaS directly. Overview: [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md); skill: [coinme-caas-api-clients](https://platformdocs.coinme.com/skills/coinme-caas-api-clients/SKILL.md); every page in [llms-api.txt](https://platformdocs.coinme.com/llms-api.txt).
- You do not embed the Coinme Widget.
- **Does your app collect a wallet address, on either integration?** Check it with the wallet address validator, `@coinme/wallet-address-validator` (release 1.2.0, for browsers, Node.js 18+ and React Native 0.74+ with Hermes). It works on **both** surfaces ([details](https://platformdocs.coinme.com/agents/surfaces.md#both)): it is offline and format-only, calls no Coinme service and needs no credential beyond the registry token. A Widget partner checks an address before passing it to the widget as `walletAddress`; a CaaS partner checks the send or withdrawal addresses its own screens collect. `true` means well-formed, not safe to send to. Skill: [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md); every page in [llms-wallet.txt](https://platformdocs.coinme.com/llms-wallet.txt).
- **Not sure which?** Ask your Coinme integration contact; the side-by-side comparison is in [agents/surfaces.md](https://platformdocs.coinme.com/agents/surfaces.md).
## Glossary
| Term | Meaning | Defined in |
| --- | --- | --- |
| Ramp | A complete, deployable crypto application that Orchestrator composes from shared flows for a market, partner or use case. A Ramp is a configuration, not a codebase. | [source](https://platformdocs.coinme.com/pages/explainers/orchestrator.md) |
| Ramp ID (`rampId`) | The key Orchestrator resolves the Ramp's configuration by and attributes transactions to. Coinme issues it at onboarding. | [source](https://platformdocs.coinme.com/pages/build/index.md#config) |
| `partnerKey` | Identifies your app to the Widget in the bridge handshake. Native integrations need it; a wrong or empty value means the session never becomes ready. Keep it in runtime configuration with your `rampId`. | [source](https://platformdocs.coinme.com/pages/build/index.md#config) |
| Orchestrator | The Coinme Widget: one web app that runs the whole customer experience, configured per Ramp ID. | [source](https://platformdocs.coinme.com/pages/explainers/orchestrator.md) |
| Coinme Widget | An Orchestrator Ramp running inside a partner's iframe or WebView, reached through the Widget SDK. | [source](https://platformdocs.coinme.com/pages/build/index.md) |
| Flow | One customer journey inside the widget (identity verification, buy, sell, send, cash pickup, history, account); your Ramp decides which run. | [source](https://platformdocs.coinme.com/pages/explainers/flows.md) |
| Bridge (Messaging Bridge) | The live two-way postMessage channel between a partner's app and the widget: handshake, one configuration, then events out and updates in for as long as the container lives. | [source](https://platformdocs.coinme.com/pages/explainers/bridges.md) |
| Bridge Proxy | The backend-only alternative to the bridge: the partner's backend posts a configuration and receives a widget URL with a short-lived token, and backend webhooks report completion. There is no live channel. | [source](https://platformdocs.coinme.com/pages/explainers/bridges.md) |
| Framekit | The web Widget SDK, `@coinme/coinme-bridge-framekit`: a React component or plain script that mounts the widget in an iframe and runs the bridge. | [source](https://platformdocs.coinme.com/pages/build/web/overview.md) |
| CoinmeBridge | The native Widget SDKs for iOS (Swift) and Android (Kotlin): the widget in a WebView with the same configuration and events as Framekit. | [source](https://platformdocs.coinme.com/pages/build/native/ios/overview.md) |
| `CoinmeConfig` (session intent) | The one configuration object the SDK sends across the bridge: identity, theme, language, pre-filled transaction values and locks, wallet, location and tracking ids. It overlays the Ramp's configuration for one session without redefining it. Every `updateConfig` reaches the widget at once, but only theme and language should change while a transaction is under way; transaction fields set up the next one. | [source](https://platformdocs.coinme.com/pages/build/index.md#config) |
| Compliance overlay | The rules for the user's region in Coinme's remote configuration for your Ramp, applied on top of its base configuration. They can only take away from what the base offers or add steps before the user proceeds, never grant. Coinme sets them, and they can change. | [source](https://platformdocs.coinme.com/pages/explainers/configuration.md) |
| Remote configuration | Coinme's remote configuration for your Ramp: what the Ramp offers and the rules for each region, keyed by Ramp ID. Coinme authors it. | [source](https://platformdocs.coinme.com/pages/explainers/configuration.md) |
| GreenDot | The cash on-ramp: buying crypto with cash at retail locations. | [source](https://platformdocs.coinme.com/pages/explainers/configuration.md) |
| Readycode | The cash off-ramp: selling crypto for cash picked up at an ATM. | [source](https://platformdocs.coinme.com/pages/explainers/configuration.md) |
| Bridge events | The typed events the Widget SDKs deliver, such as `sessionReady`, `transactionComplete`, `barcodeGenerated` and `closeRequested`. Which events your app receives depends on your Ramp's configuration. | [source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) |
| Simulated transaction mode | The widget runs its full path without moving real funds: crypto on testnets, card payments with test cards, real but unusable barcodes. | [source](https://platformdocs.coinme.com/pages/explainers/faq.md#simulated-transaction-mode) |
| CaaS (Coinme-as-a-Service) | Coinme's services for partners that keep their own users: onboarding and KYC, vaulting, risk and transactions, reached through the CaaS SDKs in the partner's app and the CaaS API from the partner's backend. | [source](https://platformdocs.coinme.com/agents/surfaces.md) |
| CaaS API clients (`@coinme/*-api-client`) | Server-side convenience wrappers: typed TypeScript packages for calling the CaaS REST API from a Node.js backend, one package per area of the API (core, quotes, transactions, history, send and more), installed from a private registry. Not for browsers or apps. | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| `AuthService` | The class in `@coinme/core-api-client` that exchanges a partner ID and client secret for a bearer token and refreshes it; it holds the client secret, so it runs only in the backend, and it throws if created in a browser, WebView or React Native app. | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| `customerId` | The id of a customer onboarded to CaaS, returned by the Onboarding SDK once the customer is onboarded. | [source](https://platformdocs.coinme.com/docs/coinme-onboarding-sdk.md) |
| Region status (Compliance SDK) | Where a region stands with Coinme: `onboardable` (operating, and new customers can onboard), `operating` (no new customers; whether anything can be transacted there depends on its rail exclusions), `notOperating` (listed, but Coinme does not operate there) or `unknown` (an ISO code Coinme does not list). Every region is an ISO 3166-2 code (`US-NY`); a short code or a name throws `invalidRegion` rather than being treated as unknown, and unknown fails closed. | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) |
| Attestation | A record that an onboarded customer accepted a consent or a transactional disclosure, with the region, the `policyVersion` in force and the exact text they saw (`locale`, `contentHash`). Recorded through the Compliance SDK after onboarding; not available in the Compliance SDK beta at this time. | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) |
| Non-documentary KYC | Identity verification from the details the customer types (email, name, address, phone, date of birth, SSN), with no document upload. | [source](https://platformdocs.coinme.com/docs/coinme-onboarding-sdk.md) |
| Transient Auth Token (onboarding token) | A 10-minute token the partner's backend mints with `POST /services/browserAuth` for one customer and one kind of call: the Vault SDK's payment-method submit (`payment-methods` scope) or the Onboarding SDK's onboarding submit (`onboarding` scope, minted for the sign-up session) and its phone verification calls (`onboarding` scope, minted for the `customerId` onboarding returned, from the partner's own record and never from the client; it is the only thing binding the send and the check to that customer, with no challenge ID or session to pass between them; the partner builds the backend route that mints it, which looks up the signed-in user and mints for the `customerId` saved when onboarding succeeded, so customer IDs cannot be mixed up), or the Compliance SDK's attestation reads and records (`attestations` scope, minted for the onboarded customer; not available in the beta at this time). The client sends it as `Authorization: Bearer`; it is never stored. Never pass the partner access token to any of these SDKs in its place. The Risk SDK takes no token at all. | [source](https://platformdocs.coinme.com/docs/transient-auth-token.md) |
| Partner access token | The token a partner's backend gets from `POST /services/authorize` with its API client ID and client secret. It authorizes every CaaS endpoint, mints Transient Auth Tokens, and never leaves the backend. Never pass it to any Coinme SDK. | [source](https://platformdocs.coinme.com/docs/transient-auth-token.md) |
| Secure field (hosted field) | An input rendered by the vault provider in an iframe, so sensitive values such as a card number or SSN go straight to Coinme's vault without passing through the partner's code. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md) |
| Risk session tag | The `webSessionID` the Risk SDK's session-tag call returns (`getSessionTag()` on the web, `getPartnerSessionTag()` on iOS, Android and React Native, neither taking an auth token); it becomes the session key for later risk calls, and the Vault SDK's payment-method submit requires it as `webSessionId`. A tag lives 30 minutes from when it was issued, so it is fetched right before each add-payment-method call and each order. | [source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md) |
| `clientId` (Risk) | Identifies an integration to the Risk Engine; the Risk SDK refuses to initialise without it. One per environment. | [source](https://platformdocs.coinme.com/pages/build/agents.md) |
| Wallet address validation (`validateAddress`) | A format-only check, offline, that an address is well-formed for an asset and chain: its length and characters, network prefix and checksum. It comes from `@coinme/wallet-address-validator` and works on both surfaces. `true` does not mean the address exists, is the customer's or is safe to send to, and an unsupported asset or chain throws rather than returning `false`. | [source](https://platformdocs.coinme.com/docs/wallet-address-validator.md) |
| `chainType` | The chain a wallet address is on, passed to `validateAddress` as a chain id or alias (`stellar`, `tron`, `erc20`). Strict mode requires it for assets on more than one chain, such as `usdc` and `usdt`, and throws when the chain does not use the currency's address format. | [source](https://platformdocs.coinme.com/docs/wallet-address-validator.md#chains-and-chaintype) |
| Embed allowlist | The list of web hostnames Coinme lets the widget render inside. A deployed site must be added; local development hosts work against the stage Widget without an allowlist entry. | [source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) |
## What you touch, and what is internal
The explainers describe how the platform is built, including detail no integrator configures. Use this table to tell the two apart.
| Concept | For an integrator | What it is to you |
| --- | --- | --- |
| `rampId`, `partnerKey`, `orchestratorUrl` | you set or handle it | Identity of a Widget integration, issued by Coinme. |
| `CoinmeConfig` and `updateConfig` | you set or handle it | Session intent: pre-fill, locks, theme, language, tracking ids. Change transaction fields between transactions, not during one. |
| Bridge events | you set or handle it | What your app reacts to: session ready, transaction outcomes, barcodes, close. |
| Onboarding, Compliance, Vault and Risk SDK APIs and their tokens | you set or handle it | The CaaS integration surface in your app. |
| CaaS API clients, `AuthService`, partner ID and client secret | you set or handle it | The CaaS integration surface in your backend. |
| The wallet address validator (`validateAddress`, `isSupported`) | you set or handle it | A format check for the wallet addresses your app collects, on either surface; it calls no Coinme service. |
| Your Ramp's configuration and compliance overlays | internal: understand, do not configure | Coinme authors them; they explain why a user sees what they see. |
| How the Widget is built and configured inside Coinme | internal: understand, do not configure | Coinme operates it; nothing here is a partner setting. |
## What exists today
Pages mark capabilities in beta (published and installable, fine for development builds, not generally available: check with your Coinme integration contact before production), or in development; do not build against an in-development capability as present. Anything not listed here is not documented on this site; ask your Coinme integration contact rather than assuming it exists.
| Capability | Status | Stated in |
| --- | --- | --- |
| Widget SDK on web, iOS and Android | shipped | [source](https://platformdocs.coinme.com/pages/build/index.md) |
| Onboarding SDK for JavaScript & React | shipped | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) |
| Onboarding SDK for React Native | shipped | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) |
| Compliance SDK for JavaScript & React (1.1.3, published but not generally available) | beta | [source](https://platformdocs.coinme.com/docs/coinme-compliance-sdk.md) |
| Compliance SDK for React Native (1.0.2, published but not generally available) | beta | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) |
| Vault SDK on JavaScript, iOS, Android, React Native | shipped | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md) |
| Risk SDK on web, iOS, Android, React Native | shipped | [source](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) |
| Wallet address validator 1.2.0 (browsers, Node.js 18+, React Native 0.74+ with Hermes; both surfaces) | shipped | [source](https://platformdocs.coinme.com/docs/wallet-address-validator.md) |
| Phone verification after onboarding (part of the Onboarding SDK in the releases on this site, 1.7.1 on the web and 1.2.1 on React Native; KYC is not complete until the customer's phone is verified) | shipped | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#phone-verification) |
| CaaS API clients 2.0.0 (1.x is deprecated; until 2.0.0 is published the registry serves 1.x) | in development | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| Custody and cash ramp API clients (not yet published; they publish with the 2.0.0 release, as version 0.1.0) | in development | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| Design-token theming (light / dark via `theme`) | shipped | [source](https://platformdocs.coinme.com/pages/explainers/platform.md) |
## Not covered on this site
Newcomers ask about these, and this site does not answer them. Say so, and send the question to the right place, rather than guessing or inferring an answer from examples.
| Topic | What this site says | Where the answer is |
| --- | --- | --- |
| Supported assets, chains, countries and US states | No list of what Coinme offers. The [wallet address validator's list](https://platformdocs.coinme.com/docs/wallet-address-validator-supported-assets.md) is the assets and chains it can check addresses for, not what Coinme lets a customer buy, sell or send. For a CaaS integration, the [Compliance SDK](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#regions) returns the regions Coinme lists, with whether it operates and onboards in each, at runtime (in beta). Assets appear only in examples (`BTC`, `ETH`, `POL`, `USDC`); [the configuration explainer](https://platformdocs.coinme.com/pages/explainers/configuration.md) uses illustrative regions only. What a given Ramp offers is in its configuration. The [sanctioned-jurisdictions list](https://platformdocs.coinme.com/pages/explainers/faq.md#sanctioned-jurisdictions) is about where the demo apps run, not where you may operate. | Ask your Coinme integration contact. Coverage is per Ramp and per region. |
| Fees and pricing | Nothing. | Ask your Coinme integration contact. |
| Support and bug reporting | No support channel, issue tracker or status page. For a web embed that does not load, [framekit-doctor](https://platformdocs.coinme.com/pages/build/web/doctor.md) diagnoses the integration. | Ask your Coinme integration contact. |
| Changelog and release notes | None. The current release of each SDK is in [skills/index.json](https://platformdocs.coinme.com/skills/index.json) and in each SDK page's front matter (`version`). | Ask your Coinme integration contact. |
| Webhooks (registration, payload, signing, retries) | Named as the way the Bridge Proxy reports completion, in [the bridge explainer](https://platformdocs.coinme.com/pages/explainers/bridges.md); not specified anywhere. | Ask your Coinme integration contact. |
| Server-side transaction status | Nothing. A Widget integration learns outcomes in the client, from bridge events such as `transactionComplete` and `barcodeGenerated` ([How to use (web)](https://platformdocs.coinme.com/pages/build/web/how-to-use.md)). | Ask your Coinme integration contact. |
| The Bridge Proxy API | Described as a pattern in [the bridge explainer](https://platformdocs.coinme.com/pages/explainers/bridges.md): your backend posts a configuration and receives a widget URL with a short-lived token. Its build guide is not on this site. | Ask your Coinme integration contact. |
## Where to find the answer
| If the question is | Read |
| --- | --- |
| What is the platform, which surface am I on, which SDKs do I need? | [The agent primer](https://platformdocs.coinme.com/agents/primer.md), then [agents/surfaces.md](https://platformdocs.coinme.com/agents/surfaces.md). |
| How do I integrate SDK X on platform Y? | Its skill: [skills/index.json](https://platformdocs.coinme.com/skills/index.json) lists every skill with its surface, platform, package and version. |
| Did my call succeed? What does this error code mean: fix, retry, or stop and ask? | [Reading results](https://platformdocs.coinme.com/agents/results.md): HTTP 200 is not success, the error envelope, common codes by what to do, lifetimes and limits, and what to send when something fails. |
| Every document for one SDK | The [Library](https://platformdocs.coinme.com/pages/build/library.md), or that SDK's `llms-.txt` slice. |
| Which `CoinmeConfig` fields exist, which are required, which can change mid-session? | The field table on [Build](https://platformdocs.coinme.com/pages/build/index.md#config). |
| Which widget events will my app receive? | [Build](https://platformdocs.coinme.com/pages/build/index.md) for the four that need an answer; [How to use (web)](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) for the typed set and forwarding. |
| Bridge or Bridge Proxy? | [The bridge explainer](https://platformdocs.coinme.com/pages/explainers/bridges.md). |
| Why does a user see (or not see) a rail, asset or disclosure? | [The configuration explainer](https://platformdocs.coinme.com/pages/explainers/configuration.md): base config, compliance overlay, session intent. |
| In my own CaaS screens, which states can I offer, and which rails, assets, consents and disclosures apply in a region? | The [Compliance SDK](https://platformdocs.coinme.com/docs/coinme-compliance-sdk.md): its [JavaScript & React guide](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) covers region status, the rule helpers, consents and disclosures, localized copy and attestations, with an end-to-end walkthrough. It is in beta and advisory. For a React Native app, its [React Native guide](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) covers the same SDK, also in beta. |
| How do I check a wallet address before sending, or before passing it to the widget? | The [wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md) on either surface: `validateAddress` with `strict: true` and the asset's `chainType`, trimmed input, and the three outcomes (valid, invalid, unsupported) handled apart. [Supported assets and chains](https://platformdocs.coinme.com/docs/wallet-address-validator-supported-assets.md) lists every asset and chain it can validate; its skill is [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md). |
| What does a Ramp contain, and how is a new one stood up? | [The Orchestrator explainer](https://platformdocs.coinme.com/pages/explainers/orchestrator.md). |
| Which credentials do I need from Coinme, and how do I get them? | The integrator reference for your surface: [Widget / Ramp](https://platformdocs.coinme.com/agents/ramp-reference.md) or [CaaS](https://platformdocs.coinme.com/agents/caas-reference.md). |
| Which environments and hosts are there, and what do I set for each? | The integrator reference: [Widget / Ramp](https://platformdocs.coinme.com/agents/ramp-reference.md#environments) or [CaaS](https://platformdocs.coinme.com/agents/caas-reference.md#environments). |
| Which version of an SDK is current, and is it released yet? | [SDK versions](https://platformdocs.coinme.com/pages/build/versions.md) lists every SDK's current release, generally available or beta (published, fine for development builds, not generally available), and the SDKs still in development; [versions.json](https://platformdocs.coinme.com/versions.json) has the same list as JSON. Each skill's front matter, and each page's, carries the same version and a `status: "beta"` where it applies. |
| Which platform and framework versions are supported? | The integrator reference: [Widget / Ramp](https://platformdocs.coinme.com/agents/ramp-reference.md#platform-requirements) or [CaaS](https://platformdocs.coinme.com/agents/caas-reference.md#platform-requirements). |
| What must change before going live? | The go-live checklists: [Widget / Ramp](https://platformdocs.coinme.com/agents/ramp-reference.md#go-live-checklists) or [CaaS](https://platformdocs.coinme.com/agents/caas-reference.md#go-live-checklists). |
| How do I create a verified test customer in the stage Widget, and which test identities can I use? | [Creating Widget test accounts in stage](https://platformdocs.coinme.com/docs/widget-test-accounts.md) and [Test identities for Coinme KYC](https://platformdocs.coinme.com/docs/widget-test-identities.md); [Expected behavior in stage](https://platformdocs.coinme.com/docs/widget-stage-behavior.md) covers failed verification, test cards, cash locations and testnet use. The identities are fake and work wherever Coinme performs identity verification (KYC): in the Widget and in Coinme onboarding for CaaS partners (the Onboarding SDK's sandbox environment and the onboarding API). |
| My web embed is deployed but does not load | [Doctor](https://platformdocs.coinme.com/pages/build/web/doctor.md) and the allowlist callout in [How to use (web)](https://platformdocs.coinme.com/pages/build/web/how-to-use.md). |
| How does my backend get the token the Vault, Onboarding or Compliance SDK sends? | [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md): exchange the API client ID and secret for a partner access token, then mint a 10-minute token per customer or sign-up session, with the scope of the call (`payment-methods`, `onboarding` or `attestations`, the last not available in the Compliance SDK beta at this time). Never pass the partner access token to the SDK; the `Authorization` header carries only the Transient Auth Token from `POST /services/browserAuth`. |
| How does my backend link an onboarded customer to its own sign-up session? | [Example: linking onboarding to your backend session](https://platformdocs.coinme.com/docs/onboarding-sdk-session-example.md), a complete example of the two backend routes and the checks; the concepts are in the [Onboarding SDK guide](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#how-do-i-associate-an-onboarding-with-my-own-backend-session). |
| Is there a REST API? How do I call CaaS from my backend? | [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) for Node.js, one reference page per package, all in [llms-api.txt](https://platformdocs.coinme.com/llms-api.txt); the API reference itself is on docs.coinme.com, linked from that page. |
| Pricing, supported assets or states, webhooks, support, release notes? | Not covered on this site: see [what is not covered](https://platformdocs.coinme.com/agents/primer.md#not-covered) and ask your Coinme integration contact. |
| Is this a real transaction? Can I use it from my country? | [The FAQ](https://platformdocs.coinme.com/pages/explainers/faq.md). |
---
---
title: "Two ways to build on Coinme"
url: "https://platformdocs.coinme.com/agents/surfaces.md"
markdown: "https://platformdocs.coinme.com/agents/surfaces.md"
summary: "The Coinme App Platform has two implementation surfaces: the Coinme Widget (a complete Ramp a transactional partner embeds, whose users become Coinme customers) and Coinme-as-a-Service (SDKs and services a partner with its own users composes into its own app). Who owns the user, who owns the transaction, which SDKs and credentials apply, and what each does not need."
---
# Two ways to build on Coinme
The Coinme App Platform has two implementation surfaces. They differ first in who owns the end user, and that decides which SDKs, credentials and responsibilities apply. Every SDK on this site belongs to exactly one of them, except an SDK that works the same on both, which is listed under each and in its own section below. Page front matter, `skills/index.json` and `versions.json` carry the same value as a `surface` field: `ramp`, `caas`, or `both`.
| | Widget / Ramp integration | Coinme-as-a-Service (CaaS) integration |
| --- | --- | --- |
| For | For transactional partners: a partner that wants regulated crypto buying and selling inside its own product without building it. | For partners with their own user base and their own application, who want Coinme to perform regulated services for those users. |
| The end user | The end user is onboarded as a Coinme customer, inside the widget. Sign-in, KYC, payment and receipts all happen in the Coinme Widget. | The end users are the partner's customers. Coinme onboards them to CaaS and verifies them (KYC) as a service, and returns a `customerId`, but they are not Coinme consumer users and never see a Coinme app. |
| The transaction | The transaction belongs to the partner: the partner decides when the widget opens and can pre-fill and lock the amount, asset, payment method and destination wallet for the session. | The partner owns the user experience end to end and calls Coinme services from its own UI and backend. |
| Coinme provides | A complete application (a Ramp) composed by Orchestrator, with its flows, compliance rules, KYC, risk signals, payment rails and receipts. Coinme is the licensed money transmitter. | Services the partner composes: customer onboarding with non-documentary KYC, secure capture and vaulting of sensitive data such as card details and the SSN, device and behavioural risk signals, and the transactions themselves. |
| The partner builds | A container for the widget and the reaction to its events: an iframe on the web (Framekit), a view controller on iOS or a fragment on Android (CoinmeBridge). The Bridge Proxy is a backend-only variant with no live channel. | Its own screens and backend, with Coinme SDKs for the parts that must not touch partner code (secure fields), that feed Coinme systems (risk signals) or that apply Coinme's regional compliance rules in its screens (the Compliance SDK, in beta). Its backend calls the CaaS API directly or through the CaaS API clients for Node.js. |
| Choose it when | Choose it when the partner wants the whole experience supplied and its users can be Coinme customers. | Choose it when the partner keeps its own users, brand and flows and needs Coinme as a regulated back end. |
## Widget / Ramp integration
For transactional partners: a partner that wants regulated crypto buying and selling inside its own product without building it.
### SDKs
| SDK | Family | Platform | Package | Agent skill |
| --- | --- | --- | --- | --- |
| [Framekit](https://platformdocs.coinme.com/pages/build/web/overview.md) | Widget SDK | Web | `@coinme/coinme-bridge-framekit` | [coinme-widget-web](https://platformdocs.coinme.com/skills/coinme-widget-web/SKILL.md) |
| [CoinmeBridge for iOS](https://platformdocs.coinme.com/pages/build/native/ios/overview.md) | Widget SDK | iOS | `CoinmeBridge · Swift` | [coinme-widget-ios](https://platformdocs.coinme.com/skills/coinme-widget-ios/SKILL.md) |
| [CoinmeBridge for Android](https://platformdocs.coinme.com/pages/build/native/android/overview.md) | Widget SDK | Android | `CoinmeBridge · Kotlin` | [coinme-widget-android](https://platformdocs.coinme.com/skills/coinme-widget-android/SKILL.md) |
| [Wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md) | Wallet addresses (both integrations) | Web | `@coinme/wallet-address-validator` | [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md) |
### What you get from Coinme first
- **`rampId`**: Names the Ramp the widget loads; issued at onboarding.
- **`partnerKey`**: Identifies your app to the Widget in the bridge handshake. Native integrations need it; keep it in runtime configuration with your rampId.
- **Embed allowlist entry**: Every web hostname that embeds the widget must be added by Coinme. Local development hosts work against the stage Widget without an allowlist entry.
- **`COINME_REGISTRY_TOKEN`**: Read-only token for the private package registry that serves the Widget SDKs.
### What you do not need
The widget itself needs none of the Onboarding, Vault or Risk SDKs: it carries its own onboarding, card capture and risk signals inside its frame. The Risk SDK's session-tag call does accept an `x-ramp-id` header for Ramp partners; this site does not say when a Ramp partner also runs the Risk SDK outside the widget, so ask your Coinme integration contact before adding it.
### Read next
- [agents/ramp-reference.md](https://platformdocs.coinme.com/agents/ramp-reference.md): environments, everything to get from Coinme and how, platform requirements, go-live checklists
- [llms-widget.txt](https://platformdocs.coinme.com/llms-widget.txt)
- [llms-wallet.txt](https://platformdocs.coinme.com/llms-wallet.txt)
- [llms-testing.txt](https://platformdocs.coinme.com/llms-testing.txt)
- [skills/index.json](https://platformdocs.coinme.com/skills/index.json), filtered by `"surface": "ramp"` or `"surface": "both"`
## Coinme-as-a-Service (CaaS) integration
For partners with their own user base and their own application, who want Coinme to perform regulated services for those users.
### SDKs
| SDK | Family | Platform | Package | Agent skill |
| --- | --- | --- | --- | --- |
| [Risk SDK for Web](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md) | Risk SDK | Web | `@coinme-security/risk-sdk-js` | [coinme-risk-web](https://platformdocs.coinme.com/skills/coinme-risk-web/SKILL.md) |
| [Risk SDK for iOS](https://platformdocs.coinme.com/docs/risk-sdk-for-ios-native-apps.md) | Risk SDK | iOS | `CoinmeRisk · Swift` | [coinme-risk-ios](https://platformdocs.coinme.com/skills/coinme-risk-ios/SKILL.md) |
| [Risk SDK for Android](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md) | Risk SDK | Android | `CoinmeRisk · Kotlin` | [coinme-risk-android](https://platformdocs.coinme.com/skills/coinme-risk-android/SKILL.md) |
| [Risk SDK for React Native](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md) | Risk SDK | React Native | `@coinme-security/risk-sdk-react-native` | [coinme-risk-react-native](https://platformdocs.coinme.com/skills/coinme-risk-react-native/SKILL.md) |
| [Vault SDK for JavaScript](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md) | Vault SDK | Web | `@coinme-security/vault-sdk-js` | [coinme-vault-js](https://platformdocs.coinme.com/skills/coinme-vault-js/SKILL.md) |
| [Vault SDK for iOS](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md) | Vault SDK | iOS | `CoinmeVault · Swift` | [coinme-vault-ios](https://platformdocs.coinme.com/skills/coinme-vault-ios/SKILL.md) |
| [Vault SDK for Android](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md) | Vault SDK | Android | `CoinmeVault · Kotlin` | [coinme-vault-android](https://platformdocs.coinme.com/skills/coinme-vault-android/SKILL.md) |
| [Vault SDK for React Native](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-react-native.md) | Vault SDK | React Native | `@coinme-security/vault-sdk-react-native` | [coinme-vault-react-native](https://platformdocs.coinme.com/skills/coinme-vault-react-native/SKILL.md) |
| [Onboarding SDK for JavaScript & React](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) | Onboarding SDK | Web | `@coinme-security/onboarding-sdk-react` | [coinme-onboarding-react](https://platformdocs.coinme.com/skills/coinme-onboarding-react/SKILL.md) |
| [Onboarding SDK for React Native](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) | Onboarding SDK | React Native | `@coinme-security/onboarding-sdk-react-native` | [coinme-onboarding-react-native](https://platformdocs.coinme.com/skills/coinme-onboarding-react-native/SKILL.md) |
| [Compliance SDK for JavaScript & React](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) | Compliance SDK | Web | `@coinme-security/compliance-sdk-react` | [coinme-compliance-react](https://platformdocs.coinme.com/skills/coinme-compliance-react/SKILL.md) |
| [Compliance SDK for React Native](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) | Compliance SDK | React Native | `@coinme-security/compliance-sdk-react-native` | [coinme-compliance-react-native](https://platformdocs.coinme.com/skills/coinme-compliance-react-native/SKILL.md) |
| [Core API client](https://platformdocs.coinme.com/docs/caas-core-api-client.md) | CaaS API clients | Server | `@coinme/core-api-client` | [coinme-caas-api-clients](https://platformdocs.coinme.com/skills/coinme-caas-api-clients/SKILL.md) |
| [Prove onboarding API client](https://platformdocs.coinme.com/docs/caas-prove-onboarding-api-client.md) | CaaS API clients | Server | `@coinme/prove-onboarding-api-client` | none yet |
| [Quotes API client](https://platformdocs.coinme.com/docs/caas-quotes-api-client.md) | CaaS API clients | Server | `@coinme/quotes-api-client` | none yet |
| [Transactions API client](https://platformdocs.coinme.com/docs/caas-transactions-api-client.md) | CaaS API clients | Server | `@coinme/transactions-api-client` | none yet |
| [History API client](https://platformdocs.coinme.com/docs/caas-history-api-client.md) | CaaS API clients | Server | `@coinme/history-api-client` | none yet |
| [Locations API client](https://platformdocs.coinme.com/docs/caas-locations-api-client.md) | CaaS API clients | Server | `@coinme/locations-api-client` | none yet |
| [Send API client](https://platformdocs.coinme.com/docs/caas-send-api-client.md) | CaaS API clients | Server | `@coinme/send-api-client` | none yet |
| [Custody API client](https://platformdocs.coinme.com/docs/caas-custody-api-client.md) | CaaS API clients | Server | `@coinme/custody-api-client` | none yet |
| [Cash ramp API client](https://platformdocs.coinme.com/docs/caas-cash-ramp-api-client.md) | CaaS API clients | Server | `@coinme/cash-ramp-api-client` | none yet |
| [Wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md) | Wallet addresses (both integrations) | Web | `@coinme/wallet-address-validator` | [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md) |
### What you get from Coinme first
- **Transient Auth Token**: 10-minute token the partner's backend mints at `POST /services/browserAuth` for each Onboarding submit, Onboarding phone verification call or Vault payment-method submit; never stored in the browser.
- **API client ID and client secret**: Exchanged by the partner's backend at `POST /services/authorize` for the partner access token that mints Transient Auth Tokens. Not the partner ID, and not the Risk SDK `clientId`.
- **`clientId`**: Identifies the integration to the Risk Engine; one per environment.
- **`x-partner-id`**: Partner identifier sent as a header on Risk session-tag requests.
- **partnerId and clientSecret**: The partner credentials the backend exchanges for a CaaS API bearer token (AuthService in the CaaS API clients); one pair per environment, kept in the server's secret store.
- **`COINME_CAAS_REGISTRY_TOKEN`**: Read-only token for the registry that serves the CaaS API clients (https://npm.coinme.com/coinme-caas/); not the same token as the SDK registry.
- **SDK registry token**: Read-only token for the private package registry that serves the SDKs; each guide's install steps name the environment variable they read.
### What you do not need
A CaaS integration does not embed the Coinme Widget. Each CaaS SDK is used on its own or together with the others in the partner’s own flows.
### Read next
- [agents/caas-reference.md](https://platformdocs.coinme.com/agents/caas-reference.md): environments, everything to get from Coinme and how, platform requirements, go-live checklists
- [llms-caas.txt](https://platformdocs.coinme.com/llms-caas.txt)
- [llms-onboarding.txt](https://platformdocs.coinme.com/llms-onboarding.txt)
- [llms-compliance.txt](https://platformdocs.coinme.com/llms-compliance.txt)
- [llms-vault.txt](https://platformdocs.coinme.com/llms-vault.txt)
- [llms-risk.txt](https://platformdocs.coinme.com/llms-risk.txt)
- [llms-api.txt](https://platformdocs.coinme.com/llms-api.txt)
- [llms-wallet.txt](https://platformdocs.coinme.com/llms-wallet.txt)
- [skills/index.json](https://platformdocs.coinme.com/skills/index.json), filtered by `"surface": "caas"` or `"surface": "both"`
## Both integrations (Widget / Ramp and CaaS)
These SDKs belong to neither surface alone. They run entirely in the partner's app, call no Coinme service and need no credential beyond the registry token that installs them, so a Widget / Ramp partner and a CaaS partner use them the same way. Their pages, skills and `versions.json` entries carry `surface: "both"`, and each is listed in both surfaces' SDK tables above.
| SDK | Family | Platform | Package | Agent skill | Slice |
| --- | --- | --- | --- | --- | --- |
| [Wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md) | Wallet addresses | Web | `@coinme/wallet-address-validator` | [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md) | [llms-wallet.txt](https://platformdocs.coinme.com/llms-wallet.txt) |
---
---
title: "Reading results: did the call work?"
url: "https://platformdocs.coinme.com/agents/results.md"
markdown: "https://platformdocs.coinme.com/agents/results.md"
summary: "How to tell whether a Coinme call succeeded: why HTTP 200 is not success, the error envelope, what each common error code asks you to do (fix the request, retry, clean up, or stop and ask), lifetimes and limits, confirming by reading back, what reruns collide with, and what to send your Coinme integration contact when something fails."
---
# Reading results: did the call work?
**HTTP 200 does not mean success.** Most Coinme services answer a refused request with HTTP 200 and the error in the body. Judge every call by its body: it succeeded only when the body has `data` and carries no error in any of the shapes below. A 2xx with neither is not a success either; treat it as unknown and confirm by reading back.
The SDKs and the CaaS API clients already apply this rule and turn an error body into a rejected promise or an error result. It matters most when you call an endpoint yourself with `fetch`, or put a proxy of your own between an SDK and Coinme.
## Success, and the shapes of an error
An error body takes one of three shapes:
- `{ "errorResponse": { "httpStatus": "200", "path": "…", "errorData": [{ "errorCode": "203-400-115-009", "message": "…" }] } }`, the usual envelope;
- `{ "errorData": [ … ] }`, the same list without the envelope;
- `{ "errors": [ … ] }`, which some services send when something behind them failed.
A classifier you can copy, for a call made with `fetch`:
```ts
type Outcome =
| { ok: true; data: unknown }
| { ok: false; status: number; errorCode?: string; message?: string };
// Judge a Coinme response by its body, never by its status alone.
export const readCoinmeResponse = async (response: Response): Promise => {
const text = await response.text();
let body: any;
try {
body = text === '' ? undefined : JSON.parse(text);
} catch {
body = undefined;
}
const errors =
body?.errorResponse?.errorData ?? body?.errorData ?? body?.errors;
if (Array.isArray(errors) && errors.length > 0) {
const [first] = errors;
return {
ok: false,
status: response.status,
errorCode: first?.errorCode,
message: first?.message,
};
}
if (!response.ok || body?.data === undefined) {
return { ok: false, status: response.status };
}
return { ok: true, data: body.data };
};
```
## What an error code asks you to do
An error code is four groups of digits, such as `203-400-115-009`. The second group is an HTTP-style status (`400`, `404`, `406`, `500`) even when the response itself was HTTP 200, so it is the quickest hint at the kind of failure. Match on the whole code, not on the message: messages are written for people and can mislead, as the phone-check example below shows.
### Fix the request
Retrying the same request gives the same answer. Compare the request with the guide, field by field and header by header, change it, and only then send it again.
| Code | From | Meaning |
| --- | --- | --- |
| `101-406-359-667` | Session tag (Risk SDK) | A required parameter is missing, which is also what a header under the wrong name looks like. Check every header name against the guide exactly. |
| `143-404-317-704` | Session tag (Risk SDK) | Coinme does not know the partner ID the request sent. |
| `203-400-115-009` | Phone verification check | The code was not accepted. A wrong code gives it, and so does a right code sent under the wrong field name: the check reads the code only from `phoneValidationCode`. Before asking the human for another code, check the request body. |
| `203-404-359-227` | Vault payment-method submit | The session tag sent with the card does not match the one Coinme stored for this customer and device. Mint the tag on the same device the card is submitted from, with the partner ID your partner access token carries (`metadata.PartnerId`), and send that device's fingerprint unchanged on both calls. |
### Refresh what expired and retry once
Fetch a fresh token, session tag or code, then retry the call once. If the retry fails the same way, stop and ask.
| Code | From | Meaning |
| --- | --- | --- |
| HTTP `401` or `403` | Any call with a Transient Auth Token | The token is missing, expired, or minted for another customer or scope. Mint a new one on the backend for the right customer and scope. |
| `101-500-359-000`, `270-500-203-604`, `206-500-100-999` | Session tag, onboarding | A general server error. Retry once; when it repeats, check the request for values the SDK did not produce (an edited device fingerprint, for example), then send the details listed under "What to send" to your Coinme integration contact. |
### Clean up, or use a fresh record
These say an earlier attempt already happened. Do not resubmit the same thing; reuse the earlier result, or start from a record nothing has used.
| Code | From | Meaning |
| --- | --- | --- |
| `206-400-100-001`, `270-400-203-603` (`duplicate`) | Onboarding | This identity is already a customer of this partner: one account per identity per partner. Reuse the `customerId` you saved when it was first onboarded; in a test, onboard a different test identity. |
| `231-400-313-600` | Vault payment-method submit | Card already in use: another customer of this partner holds it. In a test this is usually an earlier run that never deleted its card; delete it, or use another test card. |
### Stop and ask the human
These are decisions about a real person or a real limit, not bugs to work around. Report the code and what it means, and wait.
| Code | From | Meaning |
| --- | --- | --- |
| `206-400-100-020` (`identityVerificationFailed`) | Onboarding | Coinme could not verify the identity. No customer was created. Do not resubmit the same details. |
| `206-400-100-011`, `-012`, `-014`, `-031` to `-036` | Onboarding | Age, jurisdiction, prohibited or sanctions refusals. Final for these details. |
| `203-400-115-001`, `203-400-115-003` | Phone verification | Too many failed checks or phone changes. Further sends and checks are refused for a while; wait rather than retry. |
| `203-400-115-004`, `-006`, `-007`, `-008` | Phone verification send | The number cannot be used: recently used by another account, not a mobile number, an unsupported carrier, or already in use. The customer needs another number. |
## Lifetimes and limits
| What | Lives or allows | Past it |
| --- | --- | --- |
| Transient Auth Token | 10 minutes, for one customer and one scope | Calls are refused. Mint a fresh token on the backend just before the call, never cache one across steps. |
| Session tag (Risk SDK) | 30 minutes from when it was issued | A card submitted with an older tag is refused. Fetch a new tag on the device that will submit. |
| Phone verification code | About a minute after it is sent | Checking it fails. Enter the code as soon as it arrives; a code that arrives late needs a new send. |
| Failed phone checks | A small number per customer within a time window | The customer is refused further sends and checks for a while (`203-400-115-001`). Each wrong or malformed check counts, so fix the request before sending another. |
## Confirm by reading back
A call can be accepted and still not have done what you meant: a session tag minted with the wrong partner ID is issued normally and only fails later, at the card submit. After each step that creates something, read it back from your backend before building on it: list the customer's payment methods and find the card with status `CREATED` (and `DELETED` after a delete); keep the `customerId` onboarding returned and use it for every later call.
Phone verification has no status endpoint. The SDK reports the result of the check itself (`onVerified`, or the check's outcome); record it on your backend when it arrives. To confirm a customer's phone state after the fact, use the Partner Portal or ask your Coinme integration contact.
## What a rerun collides with
- One account per identity per partner: onboarding the same identity twice returns `duplicate`.
- A card can be held by only one customer of the partner at a time: a test that adds a card and never deletes it blocks that card for every later run (`231-400-313-600`).
- Failed phone checks accumulate per customer: a test that keeps checking wrong or malformed codes locks the customer out.
- So a test that writes should clean up whatever it created, even when it fails, and record what it created (customer IDs, payment method IDs) before it creates it, so a run killed halfway can be cleaned up by hand.
## Widget events
A Widget purchase's completion event is sent when the customer finishes the flow (presses Done on the success screen), not the moment the payment succeeds. A test that stops on the success screen never sees it; a page that waits for it to show its own confirmation waits until the customer leaves the Widget.
## Secure fields in a browser test
The Vault and Onboarding SDKs collect card numbers and SSNs in secure iframes. Browser automation that sets a field's value directly (Playwright's `fill()`, for example) is not seen by the SDK; type key by key (`pressSequentially`), then read the value back. On a slow machine keystrokes can be dropped while a field reformats itself, so type with a short delay, and type a card expiry as digits only (`1229`), letting the field add its separator.
Each secure iframe may also contain hidden autofill inputs (`aria-hidden="true"`); target the visible input.
## What to send when something fails
Send your Coinme integration contact:
- the error code from the body (not only the HTTP status), and its message;
- the `X-B3-TraceId` the request carried: the SDKs set one on every call, and if you call an endpoint yourself, set your own and log it;
- the time, in UTC, to the second;
- the endpoint and method, and the field names of the body you sent (never the values: no codes, SSNs, card numbers or tokens);
- the `customerId`, and the SDK and version.
With those, one specific call can be traced; without them, the conversation starts with questions.
## Related pages
- [Transient Auth Token](https://platformdocs.coinme.com/docs/transient-auth-token.md)
- [Test identities for Coinme KYC](https://platformdocs.coinme.com/docs/widget-test-identities.md)
---
---
title: "Integrator reference: Widget / Ramp integration"
url: "https://platformdocs.coinme.com/agents/ramp-reference.md"
markdown: "https://platformdocs.coinme.com/agents/ramp-reference.md"
summary: "For the Widget / Ramp integration: every environment and host, everything to get from Coinme and how to request it, platform and framework requirements, a go-live checklist per SDK and platform, and what this site does not state."
---
# Integrator reference: Widget / Ramp integration
## Environments
| Scope | Environment | Value you set | Host | Notes | Stated in |
| --- | --- | --- | --- | --- | --- |
| Widget (web, iOS, Android) | stage | | `https://stage-widget.coinme.com` | The URL every Build guide and demo loads while integrating; the web guide calls stage-widget "for testing". The URL you load picks the environment: `CoinmeConfig.environment` has no effect, so leave it unset. | [source](https://platformdocs.coinme.com/pages/build/index.md#credentials) |
| Widget (web, iOS, Android) | prod | | `https://widget.coinme.com` | Production. Pass it as `orchestratorUrl` (web, Android) or `orchestratorURL` (iOS); the SDK derives the trusted message origin from the URL, so it must point straight at the widget deployment, not through a redirect. | [source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) |
| Wallet address validator | none | | | Has no environment: it makes no network requests and talks to no Coinme service, so the same package and calls run in development and production. `network: 'testnet'` selects testnet address formats, not a Coinme environment. | [source](https://platformdocs.coinme.com/docs/wallet-address-validator.md) |
## What you get from Coinme, and how
Ask for all of these before you start. Keep each one where its row says; none belongs in source control.
### `COINME_REGISTRY_TOKEN` (web)
- **For**: Framekit (`@coinme/coinme-bridge-framekit`) and the wallet address validator (`@coinme/wallet-address-validator`)
- **Purpose**: Read-only token for the private npm registry `https://npm.coinme.com/coinme-sdk-frontend/`, which serves the `@coinme` scope. Used at install time; a missing registry configuration is one of the Doctor `check` findings.
- **Keep it in**: A gitignored `.env.yarn` read by `.yarnrc.yml` (or the `.npmrc` auth token for npm and pnpm); CI reads it from a secret. Never commit the real token.
- **How to get it**: Issued by Coinme as a read-only entitlement token; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md)
### Registry token (native)
- **For**: CoinmeBridge for iOS and CoinmeBridge for Android
- **Purpose**: Authenticates the Cloudsmith Swift registry `https://swift.cloudsmith.io/coinme/coinme-sdk-frontend/` (package `coinme.coinme-native-bridge-ios`, login with username `token`) and the Maven repository `https://maven.cloudsmith.io/coinme/coinme-sdk-frontend/` (artifact `com.coinme:coinme-bridge`). The Build pages and the agent skills call it `COINME_REGISTRY_TOKEN` (on Android, a Gradle property of that name); the docs.coinme.com guides write it as ``.
- **Keep it in**: iOS: the `swift package-registry login` keychain entry on each machine and a CI secret, never the project file. Android: a gitignored `gradle.properties` or `local.properties` entry the repository block reads, never a committed build file.
- **How to get it**: Issued by Coinme as an entitlement token; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/ios-quick-start.md)
### `rampId`
- **For**: Widget SDKs on web, iOS and Android
- **Purpose**: Names the Ramp the widget loads: it selects the remote configuration the widget runs with and attributes every transaction to you. Required in `CoinmeConfig`.
- **Keep it in**: Runtime configuration, not source (web: build-time variables in a gitignored env file; iOS: a gitignored `Secrets.swift` with a committed example; Android: `local.properties` surfaced through `BuildConfig`). A placeholder such as `your-ramp-id` must never ship.
- **How to get it**: Issued by Coinme at onboarding, per environment; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/pages/build/index.md#credentials)
### `partnerKey`
- **For**: CoinmeBridge for iOS and Android; Framekit only when the same integration also runs inside native WebViews
- **Purpose**: Identifies your app to the Widget in the bridge handshake. Native integrations need it; a wrong or empty value means the widget loads but the session never becomes ready (SESSION_TIMEOUT).
- **Keep it in**: Runtime configuration, in the same place as the `rampId`.
- **How to get it**: Issued by Coinme at onboarding alongside the ramp id; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/pages/build/index.md#credentials)
### `orchestratorUrl`
- **For**: Widget SDKs on web, iOS and Android
- **Purpose**: The widget 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, and its scheme, host and port must match the deployment exactly.
- **Keep it in**: Runtime configuration, one value per environment you deploy.
- **How to get it**: Listed by Build among the values that arrive at onboarding; the site names the stage and production URLs (see environments). For any other deployment, ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/pages/build/index.md#credentials)
### Embed allowlist entry
- **For**: Framekit (web)
- **Purpose**: The widget does not render inside a host it does not recognize and the handshake never completes. Local development hosts work against the stage Widget without an allowlist entry, so a passing local test does not prove a deployed site will embed. A passing Doctor probe bridge-session check proves the hostname is allowlisted.
- **Keep it in**: Coinme's side: the embed allowlist, managed by Coinme.
- **How to get it**: Send Coinme the hostname of every environment you deploy (hostname only, no scheme, no port), at the same time as you ask for the ramp ID; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md)
### Content-Security-Policy `frame-src` entry
- **For**: Framekit (web)
- **Purpose**: Lets the page frame the widget. The Doctor checks look for CSP metas that block the widget and report the CSP actually enforced.
- **Keep it in**: Your site's CSP header or meta.
- **How to get it**: Nothing to obtain: add the widget origin you load (stage or production) to `frame-src` yourself.
[source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md)
### Camera and location decision
- **For**: CoinmeBridge for iOS and Android
- **Purpose**: Camera and location are enabled by default (`allowsCamera`, `allowsLocation`). Coinme configures your Ramp according to whether you keep them; without the camera the integration cannot fall back to documentary KYC and is unavailable where that is required, and without location users enter their location by hand.
- **Keep it in**: Your Ramp configuration at Coinme, matched by the `allowsCamera` and `allowsLocation` flags and the Info.plist keys or manifest permissions you ship.
- **How to get it**: Nothing is issued: tell Coinme your decision so the Ramp is configured to match; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/ios-integration-guide.md)
### Event catalog for your Ramp
- **For**: Widget SDKs on web, iOS and Android
- **Purpose**: 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, and can rename events or combine several into one message.
- **Keep it in**: Coinme's side: your Ramp's configuration.
- **How to get it**: Coinme provides the full catalog of event names for your Ramp and enables the events you need; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md)
## Platform requirements
| SDK | Platform | Requirements | Stated in |
| --- | --- | --- | --- |
| Framekit | Web | `react` and `react-dom` >=18.0.0 as peers for the React component (`@coinme/coinme-bridge-framekit/react`). The plain-script factory `createCoinmeFrame` has zero framework dependencies and needs only a DOM element to mount into. The Doctor probe needs `playwright-core` and a locally installed Chrome. Browser minimums are not stated. Release on this site: 1.1.2. | [source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) |
| CoinmeBridge for iOS | iOS | Xcode 15.0+, Swift 5.7+, iOS 14.0+ deployment target. Swift Package Manager from the Cloudsmith Swift registry, package `coinme.coinme-native-bridge-ios`. Release on this site: 1.3.0 (the docs.coinme.com guides pin `from: "1.0.0"`). | [source](https://platformdocs.coinme.com/docs/ios-integration-guide.md) |
| CoinmeBridge for Android | Android | Android API 24+ (Android 7.0) minimum SDK, Kotlin 2.2+. Artifact `com.coinme:coinme-bridge` from the Coinme Cloudsmith Maven repository. The hosting Activity must declare `android:configChanges` so the WebView survives rotation and the keyboard. Release on this site: 1.3.0 (the docs.coinme.com guides pin 1.0.0). Android Gradle Plugin, compile SDK and JDK requirements are not stated. | [source](https://platformdocs.coinme.com/docs/android-integration-guide.md) |
| Widget SDK | React Native | No React Native Widget SDK is published. | [source](https://platformdocs.coinme.com/pages/build/library.md) |
| Wallet address validator | Web, Node.js, React Native | Node.js 18 or later; current evergreen browsers (ES2020 with `BigInt`); React Native 0.74 or later with Hermes (needs `BigInt` and `TextEncoder`). ESM and CommonJS, with TypeScript declarations for both (`moduleResolution` `node16`/`nodenext` and `bundler`); Vite, webpack, Rollup, esbuild and Metro. No runtime or peer dependencies. Release on this site: 1.2.0. | [source](https://platformdocs.coinme.com/docs/wallet-address-validator.md#compatibility) |
## Go-live checklists
### Framekit (web)
1. Replace the placeholder `rampId` with the production value Coinme issued. Add `partnerKey` only if the same integration also ships inside native WebViews.
2. Give Coinme the production hostname for the embed allowlist (hostname only, no scheme or port).
3. If your site sets a Content-Security-Policy, add the widget origin to `frame-src`.
4. Do not send `Referrer-Policy: no-referrer`; the Widget needs it to recognise your site.
5. Point `orchestratorUrl` at `https://widget.coinme.com`; stage-widget is for testing.
6. Run `framekit-doctor check .` and fix every finding: SDK installed and registry configured, frame mounted, credentials not placeholders, HTTPS Orchestrator URL, no blocking sandbox, referrer or CSP settings.
7. Run `framekit-doctor probe ` against every environment you deploy; the bridge-session check passing proves the hostname is allowlisted. Use `--json` in CI.
[source](https://platformdocs.coinme.com/pages/build/web/how-to-use.md)
### CoinmeBridge for iOS
1. Load the production URL as `orchestratorURL`; the iOS guides use `https://widget.coinme.com`.
2. The guides set `environment: "prod"`; it has no effect, so it can stay or go.
3. Use the production `rampId` and `partnerKey` Coinme issued, kept in a gitignored `Secrets.swift`.
4. Add `NSCameraUsageDescription`, `NSMicrophoneUsageDescription`, `NSPhotoLibraryUsageDescription` and `NSLocationWhenInUseUsageDescription` to Info.plist, unless you set `allowsCamera` or `allowsLocation` to false.
5. Tell your Coinme integration contact whether you keep camera and location access, so the Ramp is configured to match.
6. From 1.3.0 the package ships its own privacy manifest declaring a Device ID (not linked to the user, not used for tracking, for app functionality) and UserDefaults access (reason CA92.1); check that your App Store privacy answers account for it.
7. From 1.3.0, if your app passes its own fingerprint to the Coinme Risk or Vault SDK for iOS, set the same value as `deviceFingerprint`; otherwise leave it `nil` and the bridge sends the shared one.
8. Confirm the session reaches session ready against production. A SESSION_TIMEOUT means checking the `partnerKey` first, then that the Ramp is enabled for this environment.
[source](https://platformdocs.coinme.com/docs/ios-integration-guide.md)
### CoinmeBridge for Android
1. Load the production URL as `orchestratorUrl`; the Android guides use `https://widget.coinme.com`.
2. The guides set `environment = "prod"`; it has no effect, so it can stay or go.
3. Use the production `rampId` and `partnerKey` Coinme issued, kept in `local.properties` and surfaced through `BuildConfig`.
4. Declare `INTERNET`, `ACCESS_FINE_LOCATION`, `ACCESS_COARSE_LOCATION`, `CAMERA`, `READ_MEDIA_IMAGES` and `READ_EXTERNAL_STORAGE` (maxSdkVersion 32) in the manifest; the SDK requests them at runtime.
5. Declare `android:configChanges` on the Activity that hosts `CoinmeFragment`.
6. Tell your Coinme integration contact whether you keep camera and location access, so the Ramp is configured to match.
7. From 1.3.0, if your app passes its own fingerprint to the Coinme Risk or Vault SDK for Android, set the same value as `deviceFingerprint`; otherwise leave it null and the bridge sends the shared one.
8. Confirm the session reaches session ready against production. A SESSION_TIMEOUT means checking the `partnerKey` first, then that the Ramp is enabled for this environment.
[source](https://platformdocs.coinme.com/docs/android-integration-guide.md)
### Wallet address validator (both surfaces)
1. Validate with `strict: true`, and pass `chainType` for every asset that lives on more than one chain; strict mode requires it for `usdc` and `usdt`.
2. Trim the input and strip payment URIs before validating; `validateAddress` does neither.
3. Handle the three outcomes apart: `true` goes on to your own ownership and compliance checks, `false` shows a field error, and `UnsupportedCurrencyError` or `UnsupportedChainError` is logged as an integration issue and never lets the user send to the address.
4. Check every currency and chain pair you offer with `isSupported` at startup or in a test.
5. Collect and check memos and destination tags separately where the chain uses them.
6. Pass the checks in "Verify your integration". There is no environment to switch for production.
7. With the Widget, check the address your app collects before passing it as `walletAddress` (and locking it with `walletAddressLock`).
[source](https://platformdocs.coinme.com/docs/wallet-address-validator.md#recommended-integration)
## Not stated on this site
Ask your Coinme integration contact for these; do not guess them.
- **The `environment` field.** Build and the web guide say `CoinmeConfig.environment` has no effect and should be left unset; the docs.coinme.com native guides still set it, which is harmless. The Widget URL you load picks stage or production.
- **Native production URL.** Confirm the production Widget URL for your native apps before you ship; ask your Coinme integration contact.
- **Simulated transaction mode.** The FAQ describes the mode (testnet crypto, test cards, unusable barcodes) but not whether stage, a particular Ramp or a setting turns it on, or whether stage ever moves real funds; ask your Coinme integration contact.
- **Per-environment values.** Which of the values Coinme issues differ between stage and production is not stated; ask your Coinme integration contact for both sets together.
- **Registry token.** Build and the skills call it `COINME_REGISTRY_TOKEN`; the docs.coinme.com native guides call it an entitlement token. If a registry refuses the token you have, ask your Coinme integration contact.
- **Native go-live.** Only the web guide has a ship checklist. The iOS and Android checklists here are assembled from what the guides say changes for production; app-store review requirements for the widget, and any release sign-off from Coinme, are not stated; ask your Coinme integration contact.
- **Browser support.** No minimum browser versions are stated for Framekit; ask your Coinme integration contact.
- **Allowlist requests.** How to send hostnames for the embed allowlist, and how long adding them takes, is not stated; ask your Coinme integration contact.
- **Bridge Proxy.** The backend-only Bridge Proxy is described, but its endpoint, credentials, configuration payload and webhook contract are not on this site; ask your Coinme integration contact.
- **Risk SDK for Ramp partners.** The Risk SDK's session-tag call accepts an `x-ramp-id` header for Ramp partners, but the site does not say when a Ramp partner also runs the Risk SDK outside the widget; ask your Coinme integration contact before adding it.
---
---
title: "Integrator reference: Coinme-as-a-Service (CaaS) integration"
url: "https://platformdocs.coinme.com/agents/caas-reference.md"
markdown: "https://platformdocs.coinme.com/agents/caas-reference.md"
summary: "For the Coinme-as-a-Service (CaaS) integration: every environment and host, everything to get from Coinme and how to request it, platform and framework requirements, a go-live checklist per SDK and platform, and what this site does not state."
---
# Integrator reference: Coinme-as-a-Service (CaaS) integration
## Environments
| Scope | Environment | Value you set | Host | Notes | Stated in |
| --- | --- | --- | --- | --- | --- |
| Onboarding SDK (web) | sandbox | `'sandbox'` | `https://secure.apis.coinme.org` | `environment` is required on `CustomerOnboardingForm`, `CoinmeOnboardingProvider` and `createOnboardingVault`, read once on mount, and picks the onboarding vault and the Coinme onboarding endpoint, both built into the package; you never configure a vault ID or URL. Sandbox is for testing, with a sandbox onboarding token and a sandbox test identity from Coinme. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) |
| Onboarding SDK (web) | live | `'live'` | `https://secure.apis.coinme.com` | For real customers. Remount the provider to switch environments. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) |
| Onboarding SDK (React Native) | sandbox | `'sandbox'` | `https://secure.apis.coinme.org` | `environment` is required on `CustomerOnboardingForm`, `CoinmeOnboardingProvider` and `createOnboardingVault`, read once on mount, and picks the onboarding vault and the Coinme onboarding endpoint, both built into the package; you never configure a vault ID or URL. Sandbox is for testing, with a sandbox onboarding token and a sandbox test identity from Coinme. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) |
| Onboarding SDK (React Native) | live | `'live'` | `https://secure.apis.coinme.com` | For real customers. Mount the provider again to switch environments. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) |
| Onboarding SDK phone verification (web and React Native) | sandbox | `'sandbox'` | `https://caas-staging.coinme.com` | The phone verification calls go to the Coinme API host, a different host from the onboarding submit; the same `environment` picks it, built into the package. On the web, allow it in `connect-src`. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) |
| Onboarding SDK phone verification (web and React Native) | live | `'live'` | `https://caas.coinme.com` | For real customers; switch `environment` on the phone verification step together with the form. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) |
| Compliance SDK (web) | stage | `environment: 'stage'` | | `environment` is required on `ComplianceProvider`, `createComplianceClient` and `createHttpAttestationStore`. The SDK carries the Coinme hosts for each environment; there is no host or route to set. Use `stage` and `prod` only. | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) |
| Compliance SDK (web) | prod | `environment: 'prod'` | | Production, for real customers. | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) |
| Compliance SDK (React Native) | stage | `environment: 'stage'` | | `environment` is required on `ComplianceProvider`, `createComplianceClient` and `createHttpAttestationStore`, the same values as on the web. The SDK carries the Coinme hosts for each environment; there is no host or route to set. Use `stage` and `prod` only. | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) |
| Compliance SDK (React Native) | prod | `environment: 'prod'` | | Production, for real customers. | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) |
| Vault SDK (JavaScript, React Native) | sandbox | `'sandbox'` | | `createCoinmeVault({ environment })` or `` selects the vault, ingress host and submit path, all pre-bound by the SDK; the guides call sandbox "stage (testing)". The ingress host is not named in these guides. Test with VGS test card `4111 1111 1111 1111`, any future expiry and any 3-digit CVC. Do not pass a custom ingress (`config`) unless Coinme directs you to. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md) |
| Vault SDK (JavaScript, React Native) | live | `'live'` | | Production. Nothing else needs configuring. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-react-native.md) |
| Vault SDK (iOS, Android) | sandbox | `.sandbox` (iOS), `CoinmeVaultEnvironment.SANDBOX` (Android) | `secure.payments-stage.coinme.com` | The SDK selects the ingress host and submit path (`/caas/v2/paymentmethods`) for each environment. Do not pass a custom ingress or `RuntimeVaultConfig` unless Coinme directs you to. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md) |
| Vault SDK (iOS, Android) | live | `.live` (iOS), `CoinmeVaultEnvironment.LIVE` (Android) | `secure.payments.coinme.com` | Production; submit path `/caas/v2/paymentmethods`. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md) |
| Risk SDK (web, iOS, Android, React Native) | test | `'test'` (web, React Native), `.Test` (iOS), `Mode.Test` (Android) | | Set as `mode` in `setupCoinmeRiskEngine` with the development `clientId`. Passing the wrong mode or clientId streams behavioural data to the wrong environment and harms transaction approvals. On iOS, Android and React Native, `getPartnerSessionTag` resolves its host from `mode`; the hosts are not stated. | [source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md) |
| Risk SDK (web, iOS, Android, React Native) | prod | `'prod'` (web, React Native), `.Prod` (iOS), `Mode.Prod` (Android) | | Production builds, with the production `clientId`. | [source](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md) |
| Transient Auth Token (backend) | sandbox | | `https://caas-staging.coinme.com` | Your backend calls `POST /services/authorize` and `POST /services/browserAuth` on this host. The production base URL is provided at onboarding. | [source](https://platformdocs.coinme.com/docs/transient-auth-token.md) |
| CaaS API clients (server) | staging | `baseUrl: 'https://caas-staging.coinme.com/services'` | `https://caas-staging.coinme.com/services` | Every `APIClient` and `AuthService` takes the base URL, `/services` path included, and throws a `TypeError` at construction without one; nothing is fixed at build time, so one installation can call staging and production side by side. Create one `AuthService` per partner and environment. | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| CaaS API clients (server) | production | `baseUrl: 'https://caas.coinme.com/services'` | `https://caas.coinme.com/services` | With the production partner ID and client secret. | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| CaaS API clients (server) | secure onboarding host (both environments) | `onboardingBaseUrl` (`@coinme/prove-onboarding-api-client`) | | Customer onboarding goes to its own secure host because it carries identity data; the URL includes `/services`, and every other call in that package uses `baseUrl`. The URL is not on this site. | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| Wallet address validator | none | | | Has no environment: it makes no network requests and talks to no Coinme service, so the same package and calls run in development and production. `network: 'testnet'` selects testnet address formats, not a Coinme environment. | [source](https://platformdocs.coinme.com/docs/wallet-address-validator.md) |
## What you get from Coinme, and how
Ask for all of these before you start. Keep each one where its row says; none belongs in source control.
### SDK registry token (npm)
- **For**: Onboarding SDK (web and React Native), Compliance SDK, Vault SDK for JavaScript and React Native, Risk SDK for Web and React Native
- **Purpose**: Authenticates the private npm registry `https://npm.coinme.com/coinme-security-wrapper/` for the `@coinme-security` scope. Used only at install time. Each guide's install steps read it from an environment variable they name; use that name. The Risk React Native guide says the same token also authenticates its CocoaPods and Maven artifacts.
- **Keep it in**: An environment variable read by a committed `.npmrc` or `.yarnrc.yml`; CI reads it from a secret. Never commit the token.
- **How to get it**: Issued by Coinme, not self-serve; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md)
### Mobile registry entitlement token
- **For**: Vault SDK for iOS and Android, Risk SDK for iOS and Android
- **Purpose**: Authenticates the `coinme/coinme-sdk-mobile` registries: Swift (`https://swift.cloudsmith.io/coinme/coinme-sdk-mobile/`), CocoaPods and Maven. Each guide's setup steps name the variable or Gradle property they read; use that name.
- **Keep it in**: A gitignored `coinme.properties` or `local.properties`, or an environment variable; the Swift registry login on each machine; CI secrets. Never commit it.
- **How to get it**: Issued by Coinme; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md)
### API client ID and client secret
- **For**: Your backend, for the Onboarding, Vault and Compliance SDKs (all platforms)
- **Purpose**: Exchanged with HTTP Basic at `POST /services/authorize` for a partner access token (30 minutes in sandbox, 60 in production; read `expires_in`), which authorizes every CaaS endpoint and mints Transient Auth Tokens. The client ID is not your partner ID and not the Risk SDK `clientId`.
- **Keep it in**: Your backend's secret store. Neither they nor the partner access token ever reach a browser or an app. Never pass the partner access token to any Coinme SDK.
- **How to get it**: Issued by Coinme for API access; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/transient-auth-token.md)
### Transient Auth Token (onboarding token, attestation token)
- **For**: Onboarding SDK, Vault SDK, Compliance SDK attestation store (all platforms; attestations are not available in the beta at this time)
- **Purpose**: Minted by your backend at `POST /services/browserAuth?customerId=…` with the partner access token, and sent as `Authorization: Bearer ` on the Vault payment-method submit (`headers`, scope `payment-methods`, the default) or the onboarding submit (`getHeaders`, `scope=onboarding`, with your sign-up session identifier as `customerId`), and on the Onboarding SDK's phone verification calls (the step's or hook's `getHeaders`, `scope=onboarding`, with the `customerId` onboarding returned, read from your backend's own record and never from the client; the sign-up session token does not work there, and that token is the only thing that ties the send and the check to the customer: neither carries a customer ID, challenge ID, session or cookie), and on the Compliance SDK's attestation reads and records (the attestation store's `getHeaders`, which you write, `scope=attestations`, with the onboarded customer's `customerId`). Never the partner access token in its place. Lasts 10 minutes, cannot be refreshed, is bound to that `customerId` and accepted by one kind of call only. A failed mint can return HTTP 200 with `{"status":400}` and no `access_token`.
- **Keep it in**: In memory in the page or app, handed over by your backend for the signed-in customer or sign-up session it was minted for; never in `localStorage`, `sessionStorage`, cookies, device storage or logs.
- **How to get it**: Your backend mints a fresh one when the add-card, onboarding or consent screen opens, for each phone verification call, and again after a call fails as unauthorized (`401`/`403` for Vault, `unauthorized` for Onboarding and Compliance), retrying once.
[source](https://platformdocs.coinme.com/docs/transient-auth-token.md)
### `clientId` (Risk)
- **For**: Risk SDK (web, iOS, Android, React Native)
- **Purpose**: Identifies your integration to the Risk Engine in `setupCoinmeRiskEngine`; the SDK throws and refuses to initialise without it. Different from `partnerId`. It is not a secret and is meant to run in the browser; the partner access token and client secret never go there with it.
- **Keep it in**: Runtime configuration, not source, with the development and production values kept apart and paired with the matching `mode`.
- **How to get it**: Issued by Coinme during onboarding, two per integration (development and production); ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md)
### `x-partner-id` / `partnerId`
- **For**: Risk SDK (web, iOS, Android, React Native)
- **Purpose**: Partner identifier. On the web it is a required header in `getSessionTag` `additionalHeaders`; on iOS, Android and React Native `partnerId` is optional in `RiskEngineSetupOptions` and required in `getPartnerSessionTag`.
- **Keep it in**: Runtime configuration passed to the SDK; never hard-coded.
- **How to get it**: Provided by Coinme; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md)
### `x-ramp-id`
- **For**: Risk SDK for Web (`getSessionTag`); `rampId` option of `getPartnerSessionTag` on iOS, Android and React Native
- **Purpose**: Identifies the Ramp on session-tag requests, for Ramp partners only.
- **Keep it in**: Runtime configuration passed as an additional header.
- **How to get it**: Provided by Coinme to Ramp partners; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md)
### `apiBaseUrl` (Risk)
- **For**: Risk SDK for Web (`getSessionTag`)
- **Purpose**: Base URL of the API that serves the public `/pub/get-session-tag` endpoint.
- **Keep it in**: Runtime configuration, per environment.
- **How to get it**: Not stated on this site; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md)
### `paymentProviderId` (Vault)
- **For**: Vault SDK `submitPaymentMethod` (JavaScript, React Native, iOS, Android)
- **Purpose**: Payment provider identifier, sent as `providerId` in the payment-method request body.
- **Keep it in**: App state or runtime configuration at submit time.
- **How to get it**: Not stated on this site; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md)
### Partner ID and client secret (`partnerId`, `clientSecret`)
- **For**: CaaS API clients (`AuthService` in `@coinme/core-api-client`; every `APIClient` also takes `partnerId`)
- **Purpose**: `AuthService` exchanges them for a bearer token, caches it and fetches a new one once it expires; clients take the token and send the partner and token headers on every call. Pass a refreshed token to `updateToken`, or create clients per request.
- **Keep it in**: Your backend's secret store, out of source control and out of anything shipped to a browser or a device; one pair per environment.
- **How to get it**: Issued by Coinme per environment; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/caas-api-clients.md)
### `COINME_CAAS_REGISTRY_TOKEN` (npm)
- **For**: CaaS API clients (`@coinme/*-api-client`)
- **Purpose**: Read token for the private registry `https://npm.coinme.com/coinme-caas/`, which serves the `@coinme` scope for the API clients; a different registry from the SDKs' `coinme-security-wrapper`. Used only at install time.
- **Keep it in**: An environment variable or CI secret read by `.npmrc`; never in a committed `.npmrc`.
- **How to get it**: Issued by Coinme; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/caas-api-clients.md)
### `COINME_REGISTRY_TOKEN` (`@coinme` scope)
- **For**: Wallet address validator (`@coinme/wallet-address-validator`)
- **Purpose**: Read-only token for the private npm registry `https://npm.coinme.com/coinme-sdk-frontend/`, which serves the `@coinme` scope; a different registry from the `coinme-security-wrapper` the other CaaS SDKs install from. Used only at install time. The validator needs no other credential: it calls no Coinme service.
- **Keep it in**: An environment variable read by `.npmrc` or `.yarnrc.yml`; CI reads it from a secret. Never commit the token.
- **How to get it**: Issued by Coinme; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/wallet-address-validator.md#install)
### Phone verification after onboarding
- **For**: Onboarding SDK
- **Purpose**: Coinme does not consider KYC complete until the new customer confirms a code texted to the phone number they onboarded with. The SDK's `PhoneVerificationStep` or `usePhoneVerification` hook sends and checks the code, with a Transient Auth Token minted (`scope=onboarding`) for the `customerId` onboarding returned, not the sign-up session token and never the partner access token. That token is the only thing binding the send and the check to the customer: neither carries a customer ID, so there is no challenge ID or session to pass from the send to the check.
- **Keep it in**: Your onboarding flow, right after the form, and again on the sign-in of a customer whose phone is not verified; keep the `customerId`, the `phoneNumber` and whether it is verified on your backend.
- **How to get it**: Nothing to obtain: the step ships in the Onboarding SDK, and the token is minted by the same backend call as the onboarding token.
[source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#phone-verification)
### Phone verification token route (you build)
- **For**: Your backend, for the Onboarding SDK (web and React Native)
- **Purpose**: A route on your backend, not provided by Coinme or the SDK, that the phone verification step's or hook's `getHeaders` calls (`POST /your-api/phone-verification/token` in the examples; the path is yours). It looks up the signed-in user, reads the `customerId` saved for them when onboarding succeeded, mints a Transient Auth Token for that `customerId` (`scope=onboarding`) and returns it. It never takes a `customerId` from the page or app. Each user has one saved `customerId`, so customer IDs cannot be mixed up. Do not pass a `customerId` to the send or the check (neither takes one), never use the partner access token for them, and do not reuse the onboarding token.
- **Keep it in**: Your backend, next to the route that saves the onboarding result. The client gets only the token it returns, in memory.
- **How to get it**: You write it; the Transient Auth Token page has one way to do it, not the only way.
[source](https://platformdocs.coinme.com/docs/transient-auth-token.md#you-build)
### Sandbox test identity
- **For**: Onboarding SDK (sandbox verification)
- **Purpose**: Customer details that onboard successfully in sandbox, used to check that a submit returns a `customerId` and a repeat submit returns `duplicate`.
- **Keep it in**: Test configuration, not shipped code.
- **How to get it**: Published: use the test identity for Coinme KYC marked Yes under Verified. The identities are fake and work wherever Coinme performs identity verification in its test environment.
[source](https://platformdocs.coinme.com/docs/widget-test-identities.md)
### Content-Security-Policy entries
- **For**: Onboarding SDK (web), Vault SDK for JavaScript
- **Purpose**: `script-src` and `frame-src`: `https://js.verygoodvault.com https://js3.verygoodvault.com`; `connect-src`: the same plus `https://vgs-collect-keeper.apps.verygood.systems` and the Coinme hosts: for onboarding, the onboarding host and the Coinme API host for your environment (the submit goes to the first, the phone verification calls to the second); for Vault, the Coinme ingress host. Without them the secure fields fail to render, the submit or phone verification is blocked, or vault creation rejects.
- **Keep it in**: Your site's CSP headers, for example the framework's header config.
- **How to get it**: Nothing to obtain for the onboarding hosts, which the guide lists; the Vault guide does not name its ingress host for the web (see unstated).
[source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md)
### Store data-declaration CSV
- **For**: Risk SDK for Android and React Native
- **Purpose**: Optional pre-filled import for the Google Play Data Safety section (the React Native guide also mentions one for App Store App Privacy).
- **Keep it in**: Your store-listing workflow.
- **How to get it**: May be provided by Coinme; ask your Coinme integration contact.
[source](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md)
## Platform requirements
| SDK | Platform | Requirements | Stated in |
| --- | --- | --- | --- |
| Onboarding SDK for JavaScript & React | Web | React 18 or later for the React API (`react` and `react-dom` peers); a non-React app imports from the `/core` entry and does not install React. Browsers: Chrome / Edge 111+, Firefox 114+, Safari 16.4+ (desktop and iOS). Importing on the server is safe; the secure field is created in the browser after mount. Release on this site: 1.7.1. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) |
| Onboarding SDK for React Native | React Native | React Native 0.76 or later and React 18 or later (`react-native` and `react` peers); Expo SDK 52 or later, Expo Go included; iOS and Android; the Old and New Architecture. Install `@vgs/collect-react-native` 1.1.6 or later within `1.x` (tested with 1.2.1) as a peer from the public npm registry. No native module of its own: no config plugin, prebuild, `pod install` or Gradle change. Release on this site: 1.2.1. | [source](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) |
| Compliance SDK for JavaScript & React | Web (React optional) | React 18 or later for the React entry point (`react` and `react-dom` are optional peers); `/core` runs in any JavaScript runtime with `fetch` and timers through a platform object. Safe under server-side rendering. Release on this site: 1.1.3, in beta (published and installable, not generally available). | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) |
| Compliance SDK for React Native | React Native | React Native 0.79 or later and React 18 or later (`react-native` and `react` peers); Expo SDK 53 or later, Expo Go included; iOS and Android; Hermes; the Old and New Architecture. No native module of its own: no config plugin, prebuild, `pod install` or Gradle change. Release on this site: 1.0.2, in beta (published and installable, not generally available). | [source](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) |
| Vault SDK for JavaScript | Web | Evergreen Chrome, Firefox, Edge; Safari 10+. Vault creation is browser-only. Node at build time: any version that supports your build tool. VGS Collect.js 4.0.1 is loaded from the VGS CDN at runtime. Release on this site: 1.3.0. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md) |
| Vault SDK for iOS | iOS | Minimum iOS 15.0, Swift 5.9, VGS Collect `~> 1.18` (resolved transitively). Swift Package Manager (`coinme.CoinmeVaultSDK`) or CocoaPods (`CoinmeVaultSDK`). Xcode version not stated. Release on this site: 1.0.1. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md) |
| Vault SDK for Android | Android | Minimum Android 7.0, API level 24; compile SDK 37; JVM target 17; VGS Collect 1.11.0 (re-exported as `api`). No Compose dependency: Compose uses `AndroidView` interop. Artifact `com.coinme:vault-sdk-android`. Kotlin and Android Gradle Plugin versions not stated. Release on this site: 1.0.0. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md) |
| Vault SDK for React Native | React Native | Node 20+, React 18 or 19, React Native 0.76 or later; peer `@vgs/collect-react-native` ^1.1.6. Pure JavaScript: Expo Go works with no prebuild, and neither React Native architecture needs extra configuration. Bare projects need the usual toolchain (Xcode and CocoaPods; JDK 17 and the Android SDK). Release on this site: 1.3.0. | [source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-react-native.md) |
| Risk SDK for Web | Web | No browser or framework minimums are stated. Installed from the `@coinme-security` npm registry with npm, Yarn or pnpm. Release on this site: 1.2.0. | [source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md) |
| Risk SDK for iOS | iOS | The iOS guide states no minimum iOS, Xcode or Swift version; the React Native guide says the underlying `CoinmeRiskSDK` requires iOS 16.0+. Swift Package Manager (`coinme.CoinmeRiskSDK`) or CocoaPods through the `cocoapods-cloudsmith` plugin; includes its bundled risk components. Release on this site: 1.1.2. | [source](https://platformdocs.coinme.com/docs/risk-sdk-for-ios-native-apps.md) |
| Risk SDK for Android | Android | The Android guide states no minimum SDK or Kotlin version; the React Native guide says `risk-sdk-android` is compiled with Kotlin 2.3.0 and needs `minSdkVersion` 24+. Artifact `com.coinme:risk-sdk-android`; ProGuard / R8 keep rules required if you obfuscate. Release on this site: 1.1.2. | [source](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md) |
| Risk SDK for React Native | React Native | Node 20.9+, React 18+, React Native 0.72 to 0.81. React Native 0.82+ is not supported: the module targets the legacy (bridge) architecture, so the New Architecture must be disabled on both platforms. iOS 16.0+; Android `minSdkVersion` 24+ with Kotlin forced to 2.3.0. Expo SDK 51+ in the managed workflow with `expo prebuild`. Release on this site: 1.1.0. | [source](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md) |
| CaaS API clients | Server (Node.js) | Node.js 24.22.1 or later (or 22.23.4 or later in the 22.x line), in your backend only: `AuthService` holds the client secret and throws if it is created in a browser, WebView, Electron renderer or React Native app, so front ends reach CaaS through your backend (tests that create one need the `node` environment, not jsdom or happy-dom). Install with `@^2.0.0`; 1.x is deprecated and configured differently, and until 2.0.0 is published the registry serves 1.x. Install only the packages you call, always with `@coinme/core-api-client` for `AuthService`. | [source](https://platformdocs.coinme.com/docs/caas-api-clients.md) |
| Wallet address validator | Web, Node.js, React Native | Node.js 18 or later; current evergreen browsers (ES2020 with `BigInt`); React Native 0.74 or later with Hermes (needs `BigInt` and `TextEncoder`). ESM and CommonJS, with TypeScript declarations for both (`moduleResolution` `node16`/`nodenext` and `bundler`); Vite, webpack, Rollup, esbuild and Metro. No runtime or peer dependencies. Release on this site: 1.2.0. | [source](https://platformdocs.coinme.com/docs/wallet-address-validator.md#compatibility) |
## Go-live checklists
### Onboarding SDK (web)
1. Pass the sandbox verification first: a sandbox test identity returns a `customerId`, a repeat submit returns `duplicate`, the submit goes to the sandbox host, and phone verification with a token minted for the new `customerId` shows `codeIncorrect` for a wrong code and calls `onVerified` for the right one.
2. Switch `environment` to `'live'` on the form and on the phone verification step.
3. If your site sets a CSP, allow the vault provider domains, `https://secure.apis.coinme.com` and `https://caas.coinme.com` in `connect-src`; phone verification calls the second.
4. Verify the phone right after onboarding, with the `phoneNumber` onboarding returned and no phone input of your own, and treat no customer as onboarded or KYC-complete until it is verified; send an unverified customer who signs back in to verification first.
5. Have your backend mint the onboarding token (a Transient Auth Token with `scope=onboarding` for the sign-up session) and the phone verification token (the same call, for the new `customerId`) from the production base URL Coinme gave you; keep the API client credentials and the partner access token out of the browser.
6. Check that the route behind the phone verification step's `getHeaders` takes no `customerId` from the client and mints the token for the `customerId` your own record holds: the token is the only thing binding the verification calls to the customer, so a client-supplied ID would let one customer verify as another.
7. Do not log form values; `CoinmeOnboardingError` messages are safe to log.
[source](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md)
### Compliance SDK (web)
1. Check with your Coinme integration contact before production use: the SDK is in beta (1.1.3 is published and fine for development builds, but it is not generally available yet).
2. Pass the stage verification first: a configuration with a `policyVersion` loads, only onboardable regions are offered, every region is passed as an ISO 3166-2 code (a short code throws `invalidRegion`), an unlisted region is unavailable, consent copy renders through `ComplianceHtml`, and an excluded rail or asset is refused before your backend call.
3. Switch `environment` to `'prod'` on `ComplianceProvider` and on the attestation store.
4. Attestations are not available in the beta at this time, so do not launch a flow that depends on recording them with Coinme. `getHeaders` must return a Transient Auth Token your backend minted with `scope=attestations` for the customer, never your partner access token.
5. Keep every backend check: the SDK is advisory and Coinme's backend enforces the rules.
[source](https://platformdocs.coinme.com/docs/compliance-sdk-react.md)
### Compliance SDK (React Native)
1. Check with your Coinme integration contact before production use: the React Native SDK is in beta (1.0.2 is published and fine for development builds, but it is not generally available yet).
2. Pass the stage verification on both iOS and Android: a configuration with a `policyVersion` loads, a relaunch in airplane mode starts from the stored configuration, only onboardable regions are offered, every region is passed as an ISO 3166-2 code (a short code throws `invalidRegion`), and consent copy renders through `ComplianceText`.
3. Switch `environment` to `'prod'` on `ComplianceProvider` and on the attestation store.
4. Attestations are not available in the beta at this time, so do not launch a flow that depends on recording them with Coinme. `getHeaders` must return a Transient Auth Token your backend minted with `scope=attestations` for the customer, never your partner access token, and the app never persists it.
5. Keep every backend check: the SDK is advisory and Coinme's backend enforces the rules.
[source](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md)
### Onboarding SDK (React Native)
1. Pass the sandbox verification on both iOS and Android: a sandbox test identity returns a `customerId`, a repeat submit returns `duplicate`, the submit button enables only once every field, the SSN included, is valid, and phone verification with a token minted for the new `customerId` shows `codeIncorrect` for a wrong code and calls `onVerified` for the right one.
2. In a release build, check that no network logger or inspector is bundled and that monitoring and APM SDKs, and any `fetch` interceptor of your own, do not capture request bodies for the onboarding vault host: until the vault receives it, the SSN is in plain text in the app's JavaScript.
3. Switch `environment` to `'live'` on the form and on the phone verification step.
4. Verify the phone right after onboarding, with the `phoneNumber` onboarding returned and no phone input of your own, and treat no customer as onboarded or KYC-complete until it is verified; send an unverified customer who signs back in to verification first.
5. Have your backend mint the onboarding token (a Transient Auth Token with `scope=onboarding` for the sign-up session) and the phone verification token (the same call, for the new `customerId`) from the production base URL Coinme gave you; keep the API client credentials out of the app and never store either token on the device.
6. Check that the route behind the phone verification step's `getHeaders` takes no `customerId` from the app and mints the token for the `customerId` your own record holds: the token is the only thing binding the verification calls to the customer, so an app-supplied ID would let one customer verify as another.
7. Do not log form values; `CoinmeOnboardingError` messages are safe to log.
[source](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md)
### Vault SDK for JavaScript
1. Pass the sandbox verification with the VGS test card: the form becomes valid and a submit returns 2xx or the `CoinmeVaultError` kind you provoked.
2. Create the vault with `environment: 'live'`.
3. If your site sets a CSP, add the VGS domains and the Coinme ingress host.
4. Send a fresh transient auth token as `Authorization: Bearer ` on every submit, never the partner access token.
5. Fetch the Risk SDK session tag right before each submit and pass it as `webSessionId` (a tag lives 30 minutes). From 1.3.0, with Risk SDK for Web 1.2.0 or later, the SDK adds the `X-Device-Fingerprint` the Coinme SDKs share; otherwise pass the same value you gave the Risk SDK.
6. Treat a `configuration` `CoinmeVaultError` (from 1.2.3) as an integration fault: the `Authorization` header carried a partner access token, so fix the backend route rather than retrying. Never retry a `network` error with `timedOut: true` (from 1.2.2) without first re-listing the user's payment methods.
7. Do not pass a custom ingress unless Coinme directed you to.
[source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md)
### Vault SDK for iOS
1. Create the vault with `CoinmeVault.create(environment: .live)`.
2. Send a fresh transient auth token as `Authorization: Bearer ` on every submit, never the partner access token; never store it on the device.
3. Do not pass a `RuntimeVaultConfig` unless Coinme directed you to.
[source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md)
### Vault SDK for Android
1. Create the vault with `CoinmeVaultEnvironment.LIVE`.
2. Send a fresh transient auth token as `Authorization: Bearer ` on every submit, never the partner access token; never store it on the device.
3. Do not pass a `RuntimeVaultConfig` unless Coinme directed you to.
[source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md)
### Vault SDK for React Native
1. Set `environment="live"` on `CoinmeVaultProvider`.
2. Send a fresh transient auth token as `Authorization: Bearer ` on every submit, never the partner access token; never store it on the device.
3. Treat a `configuration` `CoinmeVaultError` (from 1.2.3) as an integration fault: the `Authorization` header carried a partner access token, so fix the backend route rather than retrying. Never retry a `network` error with `timedOut: true` (from 1.2.2) without first re-listing the user's payment methods.
4. Do not pass a custom ingress `config` unless Coinme directed you to.
[source](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-react-native.md)
### Risk SDK for Web
1. Call `setupCoinmeRiskEngine` with `mode: 'prod'` and the production `clientId`.
2. Send `x-partner-id` (and `x-ramp-id` for Ramp partners) in `getSessionTag` `additionalHeaders`.
3. Call `getSessionTag()` right before each add-payment-method call and each order and send the returned `webSessionID` as `webSessionId` (a tag lives 30 minutes; don't persist one across reloads); update the engine with the `customerId` once the user is onboarded.
[source](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md)
### Risk SDK for iOS
1. Initialise with `mode: .Prod`, the production `clientId` and your `partnerId`.
2. In App Store Connect > App Privacy, declare data collection: Coarse and/or Precise Location and Device ID, purpose App Functionality, device ID linked to user identity.
3. Add the guide's required fraud-protection disclosure to your App Store privacy policy.
4. Add `NSLocationAlwaysAndWhenInUseUsageDescription` and `NSLocationWhenInUseUsageDescription` to Info.plist and request location at runtime.
5. If behaviour biometrics are on (the default), have users agree to your privacy policy before collection.
6. Set `setCloudEntitlements` to true only with the CloudKit capability configured; otherwise the SDK crashes.
[source](https://platformdocs.coinme.com/docs/risk-sdk-for-ios-native-apps.md)
### Risk SDK for Android
1. Initialise with `Mode.Prod`, the production `clientId` and your `partnerId`.
2. Add the guide's required fraud-protection disclosure to your Google Play privacy policy.
3. In Play Console > App content > Data safety, declare Location (Approximate and Precise), Device or other IDs, App info and performance, and Files and docs.
4. Declare `INTERNET` and `ACCESS_NETWORK_STATE` (required), and only the optional permissions you disclose in your Data Safety form; request the dangerous ones you declare (location, phone state) at runtime.
5. If you use ProGuard or R8, add the keep rules the guide lists for Google Play Services and its bundled risk components.
6. If behaviour biometrics are on (the default), have users agree to your privacy policy before collection.
[source](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md)
### Risk SDK for React Native
1. Initialise with `mode: 'prod'` and the production `clientId`.
2. Every Coinme SDK in the app and your backend calls must send the same `x-device-fingerprint`. From 1.1.0 the SDKs share one for you and expose it as `getDeviceFingerprint()`, which returns a Promise. Read it in the app and send it to your server with each request; a mismatch gets payment-method and order calls rejected.
3. Complete the Google Play privacy policy disclosure and Data Safety declaration, and the App Store Connect App Privacy declarations and privacy policy disclosure.
4. Add the Android permissions and ProGuard / R8 rules, and the iOS location Info.plist keys.
5. Keep React Native at 0.81 or older with the New Architecture disabled.
6. If behaviour biometrics are on (the default), have users agree to your privacy policy before collection.
[source](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md)
### CaaS API clients
1. Point every `AuthService` and `APIClient` at `https://caas.coinme.com/services`.
2. Use the production partner ID and client secret, from your secret store.
3. Set the production `onboardingBaseUrl` if you use the onboarding client.
4. Keep the registry token in CI secrets, never in a committed `.npmrc`.
[source](https://platformdocs.coinme.com/docs/caas-api-clients.md)
### Wallet address validator (both surfaces)
1. Validate with `strict: true`, and pass `chainType` for every asset that lives on more than one chain; strict mode requires it for `usdc` and `usdt`.
2. Trim the input and strip payment URIs before validating; `validateAddress` does neither.
3. Handle the three outcomes apart: `true` goes on to your own ownership and compliance checks, `false` shows a field error, and `UnsupportedCurrencyError` or `UnsupportedChainError` is logged as an integration issue and never lets the user send to the address.
4. Check every currency and chain pair you offer with `isSupported` at startup or in a test.
5. Collect and check memos and destination tags separately where the chain uses them.
6. Pass the checks in "Verify your integration". There is no environment to switch for production.
7. In CaaS screens, check send and withdrawal addresses before your backend uses them; the check is advisory input validation, and your own ownership and screening controls still apply.
[source](https://platformdocs.coinme.com/docs/wallet-address-validator.md#recommended-integration)
## Not stated on this site
Ask your Coinme integration contact for these; do not guess them.
- **Risk `apiBaseUrl`.** The value for each environment is not stated on this site; ask your Coinme integration contact.
- **Risk session-tag hosts.** Which host each Risk `mode` resolves to is not stated; ask your Coinme integration contact.
- **Environment names.** Onboarding and Vault use `sandbox` / `live`, Risk uses `test` / `prod`, and the Vault guides call sandbox "stage (testing)". Whether Risk `test` pairs with `sandbox`, and whether either is the widget's `stage`, is not stated; ask your Coinme integration contact.
- **Simulated transactions.** Simulated transaction mode is described for the widget only; whether CaaS sandbox moves real funds or behaves the same way is not stated; ask your Coinme integration contact.
- **Partner identifier.** Whether the web `x-partner-id` header value and the native and React Native `partnerId` are the same value is not stated (only that `partnerId` differs from `clientId`); ask your Coinme integration contact.
- **Transient Auth Token in production.** The sandbox base URL for `/services/authorize` and `/services/browserAuth` is `https://caas-staging.coinme.com`; the production base URL is provided at onboarding and is not stated on this site, nor whether it is the CaaS API clients' production host; ask your Coinme integration contact.
- **`paymentProviderId`.** What value to pass, and whether it differs per environment, is not stated; ask your Coinme integration contact.
- **Vault ingress host for web and React Native.** The ingress host to allow in your Content-Security-Policy for the JavaScript and React Native SDKs is not named on this site; ask your Coinme integration contact.
- **Vault configuration on native.** Which vault values, if any, you set in your build configuration on iOS and Android; ask your Coinme integration contact before filling them.
- **Registry token.** If a registry refuses the token you have, ask your Coinme integration contact. The CaaS API clients use their own registry token, `COINME_CAAS_REGISTRY_TOKEN`.
- **Wallet address validator registry.** The validator installs from the `@coinme` registry (`coinme-sdk-frontend`), not the `@coinme-security` one the other CaaS SDKs use; whether one registry token reads both is not stated; ask your Coinme integration contact.
- **Native and web minimums.** The Risk iOS and Android guides state no minimum OS, Xcode, Swift, Kotlin or Gradle versions (only the React Native guide gives iOS 16.0+, minSdk 24 and Kotlin 2.3.0); the Risk web guide states no browser minimums; the Vault iOS guide gives no Xcode version and the Vault Android guide no Kotlin or Android Gradle Plugin version; ask your Coinme integration contact.
- **Go-live.** No CaaS guide has a production checklist or a Coinme sign-off step; the checklists here are assembled from what each guide says changes for production; ask your Coinme integration contact for anything else Coinme requires before live traffic.
- **Compliance SDK hosts.** The Coinme hosts the Compliance SDK loads its configuration, copy and attestations from are carried by the SDK and not stated on this site; if your Content-Security-Policy restricts `connect-src`, ask your Coinme integration contact.
- **API client secure host.** The `onboardingBaseUrl` value is not on this site, for either environment; ask your Coinme integration contact.
- **API client 2.0.0 release.** This site documents 2.0.0, which is not yet published; the registry serves the deprecated 1.x, configured differently. When 2.0.0 ships is not stated; ask your Coinme integration contact.
- **Custody and cash ramp clients.** `@coinme/custody-api-client` and `@coinme/cash-ramp-api-client` are not on the registry yet; ask your Coinme integration contact before planning on them.
- **Raw CaaS REST API.** The CaaS API clients cover it from Node.js; the operations themselves, for calling the API from another language, are described on docs.coinme.com's API reference, not on this site.
---
---
title: "Crypto payments, inside your app."
url: "https://platformdocs.coinme.com/#/"
markdown: "https://platformdocs.coinme.com/pages/landing.md"
summary: "Turnkey, compliant, regulated on and off ramps that live inside your product, so you focus on your business. Size the integration surface yourself: as loose as a hosted web frame, as tight as a native bridge."
---
# Crypto payments, inside your app.
Turnkey, compliant, regulated on and off ramps that live inside your product, so you focus on your business. Size the integration surface yourself: as loose as a hosted web frame, as tight as a native bridge.
## Two ways in, one widget
The same Orchestrator widget, the same configuration payload, the same events. Only the container differs. Pick the one that matches where your users are.
The page shows one integration at a time behind a toggle. Both are listed here.
### Inside a native app: Native bridges for iOS and Android
The widget runs in a WebView your app owns, with a two-way messaging bridge. Your app opens it, pre-fills the session, and listens for events.
- **Coupling**: Tight
- **You ship**: A view controller or fragment from our SDK, wired to your navigation.
- **You own**: The surrounding app, the moment of entry, and any reaction to events.
- **Effort**: About fifteen minutes to a first embed; you polish your app as you desire.
- **Guide**: [Native bridges for iOS and Android](https://platformdocs.coinme.com/pages/build/native/ios/overview.md)
### On the web: Framekit for the web
An iframe pointed at the Orchestrator, with the same bridge protocol running over postMessage. Drop a React component or a plain script into your page; theming, prefill, and events all work the same as native.
- **Coupling**: Loose
- **You ship**: One component and a Content Security Policy entry for our origin.
- **You own**: The page around the frame and what happens after a session completes.
- **Effort**: About 15 minutes to start; an afternoon including the CSP change.
- **Guide**: [Framekit for the web](https://platformdocs.coinme.com/pages/build/web/overview.md)
\* A third path, the Bridge Proxy, needs no front-end work at all: a REST call returns a hosted session URL and webhooks report completion. Its build guide is not yet on this site.
## What arrives with the widget
Everything a regulated crypto purchase needs is inside the frame. Your product supplies the user and the moment; the platform supplies the rest.
- **Regulated**: Coinme is a licensed money transmitter. The licenses, the audits, and the reporting are ours to carry.
- **Compliance included**: KYC, risk, and per-region rules run inside the flows. A restricted state changes what the widget offers; it does not change your code.
- **Cash, debit, & more**: Cash at 40,000+ retail locations, any US debit card, and more. Each rail is a feature the ramp can allow or withhold.
- **Multi-asset**: Bitcoin, Ethereum, Polygon, and more, delivered to the wallet the session names or, on Coinme's own ramp, to a custodial balance.
- **Localized**: Translations are delivered separately from the code. A new language is a content change, not a release.
- **Yours to theme**: Light or dark, pinned by your config. The widget takes the shape of the app around it.
## One widget, many experiences.
**Configuration, not code.** Which features, which assets, which regions, which theme: all of it resolves when the widget loads. Adding you as a partner is configuration on our side, not a deploy. Changing your mind later is the same.
- **Go live**: A ramp ID and a config payload.
- **Add a market**: Regional rules are applied for you.
- **Change a rail**: Flip features on or off, no release.
## Go deeper
The widget is the front of a layered platform. When you want the mechanism, it is all here.
- **[The platform, explained](https://platformdocs.coinme.com/pages/explainers/index.md)** (For everyone): Interactive explainers for the platform, one part at a time. No code required to follow.
- **[Build guides](https://platformdocs.coinme.com/pages/build/index.md)** (For engineers): Framekit for the web, CoinmeBridge for iOS and Android, and the whole SDK library. Fifteen minutes to a first embed.
Screens shown are from the Coinme demo app running the widget in [simulated transaction mode](https://platformdocs.coinme.com/pages/explainers/faq.md#simulated-transaction-mode). Live demos are not available in [sanctioned or otherwise restricted jurisdictions](https://platformdocs.coinme.com/pages/explainers/faq.md#sanctioned-jurisdictions) due to regulation. Building with a coding agent? This site is also published as plain text at [llms.txt](https://platformdocs.coinme.com/llms.txt), one Markdown file per page, so an agent can read every guide directly.
---
---
title: "Many applications from shared parts."
url: "https://platformdocs.coinme.com/#/explainers"
markdown: "https://platformdocs.coinme.com/pages/explainers/index.md"
summary: "A layered platform for building crypto applications on top of Coinme. The transactional core is built once, decomposed into versioned parts, and composed at runtime into whatever a market or a partner needs. Start with the explainers; go to the build guides when you are ready to integrate."
---
# Many applications from shared parts.
A layered platform for building crypto applications on top of Coinme. The transactional core is built once, decomposed into versioned parts, and composed at runtime into whatever a market or a partner needs. Start with the explainers; go to the build guides when you are ready to integrate.
## Explainers
One interactive page per part of the platform, written for partners evaluating or building an integration.
- **[The Coinme App Platform](https://platformdocs.coinme.com/pages/explainers/platform.md)** (Platform): A stack you can enter at any layer, one engine composing many apps, behavior resolved at runtime from three inputs.
- **[Orchestrator](https://platformdocs.coinme.com/pages/explainers/orchestrator.md)** (Engine): One widget for the whole customer experience, configured per Ramp ID, and how you get your ramp.
- **[Flows](https://platformdocs.coinme.com/pages/explainers/flows.md)** (Features): What a flow is, which flows your ramp runs, and the catalogue of customer journeys.
- **[Configuration](https://platformdocs.coinme.com/pages/explainers/configuration.md)** (Data): Base config, narrowed by region, tailored per session. Compose a session yourself and watch it resolve.
- **[The Bridge](https://platformdocs.coinme.com/pages/explainers/bridges.md)** (Embedding): What the bridge allows, hybrid app architecture out of the box, and when the Bridge Proxy fits instead.
- **[Framekit](https://platformdocs.coinme.com/pages/build/web/overview.md)** (Web embed): The iframe counterpart to the native bridges: same protocol, same rampConfig payload, with a live embed to try.
- **[FAQ](https://platformdocs.coinme.com/pages/explainers/faq.md)** (Questions): Short answers to questions that come up along the way, each with its own link.
Each explainer describes how the platform works, not every detail of how it is built. Capabilities noted as in development are marked as such and should not be read as present state.
---
---
title: "Many applications from shared parts."
url: "https://platformdocs.coinme.com/#/explainers/platform"
markdown: "https://platformdocs.coinme.com/pages/explainers/platform.md"
summary: "A layered platform for building crypto applications on top of Coinme. The transactional core is built once, decomposed into versioned parts, and composed at runtime into whatever a market or a partner needs."
---
# Many applications from shared parts.
A layered platform for building crypto applications on top of Coinme. The transactional core is built once, decomposed into versioned parts, and composed at runtime into whatever a market or a partner needs.
**Building internally and enabling a partner are the same act.** A new kind of integration is a matter of composition and configuration, not a new codebase.
## A stack you can enter at any layer
Six layers, each building on the one beneath it. **Select a layer to see what it holds.** Then pick an integration tier to see how far up a given consumer starts.
The stack, top to bottom. The last column names the integration tiers that use each layer.
| Layer | Tag | Summary | Used by tiers |
| --- | --- | --- | --- |
| Ramps | output | A complete, deployable application produced by an Orchestrator instance, aimed at a market, partner, or use case. | Ramp deployment |
| Orchestrator | engine | The composition engine. Selects flows, wires their props, and assembles them at runtime into one experience. | Ramp deployment |
| Flows | features | Feature-complete modules, each a self-contained package: KYC, buy, sell, send, cash pickup, history, account. | Ramp deployment |
| Platform services | cross-cutting | Configuration, localization and monitoring, handled by Coinme for the layers above. | Ramp deployment |
| SDK components | raw materials | The partner-facing SDKs, such as Risk, Vault and Onboarding. Usable on their own. | Ramp deployment, Bespoke SDK build |
| Backend | Coinme as a Service | Coinme's services, exposed through standard interfaces rather than re-implemented per app. | Ramp deployment, Bespoke SDK build |
### What each layer holds
- **Ramps**: The output of the platform. A ramp is a complete, deployable application produced by an Orchestrator instance and targeted at a specific market, partner, or use case. Four different ramps are four compositions, not four codebases.
- **Orchestrator**: The composition engine. It reads the ramp's configuration and localization, selects the flows a ramp calls for, and assembles them into one experience.
- **Flows**: Feature-complete modules, each self-contained with its own UI, state, and localization. The same flow runs unchanged in every ramp that offers it.
- **Platform services**: Cross-cutting capabilities the layers above rely on: configuration, localization and monitoring are handled by Coinme.
- **SDK components**: The raw materials, usable on their own with or without the rest of the platform: the partner-facing SDKs listed in the Library, such as Risk, Vault and Onboarding.
- **Backend (Coinme as a Service)**: Coinme's services, holding the business logic and data, exposed to everything above through standard interfaces rather than re-implemented per application.
### Integration tier
- **Enter at any layer**: A partner can build on the SDKs or deploy a finished ramp. The tiers are where each consumer enters the same stack.
Each tier enters the stack at its topmost layer and uses every layer beneath it; the layers above its entry point are outside it.
| Tier | Enters at | Layers it uses | Layers outside it | About |
| --- | --- | --- | --- | --- |
| Bespoke SDK build | SDK components | SDK components, Backend | Ramps, Orchestrator, Flows, Platform services | Bespoke SDK build: a partner brings their own UI and consumes the lower layers directly, taking only the capabilities they need. |
| Ramp deployment | Ramps | Ramps, Orchestrator, Flows, Platform services, SDK components, Backend | none | Ramp deployment: a partner takes a finished, Orchestrator-composed application, differing from any other ramp by configuration. |
## One engine, many apps
Different apps are different selections of the same flows under the same engine. Pick a preset and watch the same catalog compose into a different product.
Flow catalog: KYC, Cash buy, Debit buy, Sell, Send / Receive, Cash pickup, Readycode offramp, Transaction history, Account.
Each preset is one app composed by Orchestrator from that catalog. The table states the flows each preset composes and the catalog flows it leaves out.
| Preset | About | Flows composed | Catalog flows left out |
| --- | --- | --- | --- |
| Custodial cash ramp | Buy with cash at retail, pick up as cash. | KYC, Cash buy, Cash pickup, Transaction history, Account | Debit buy, Sell, Send / Receive, Readycode offramp |
| Debit-only digital ramp | Buy and sell digitally, no cash rails. | KYC, Debit buy, Sell, Transaction history, Account | Cash buy, Send / Receive, Cash pickup, Readycode offramp |
| Self-custody wallet | Buy and send to the user's own wallet. | KYC, Debit buy, Send / Receive, Transaction history, Account | Cash buy, Sell, Cash pickup, Readycode offramp |
| Full-service platform | Every rail and every flow available. | KYC, Cash buy, Debit buy, Sell, Send / Receive, Cash pickup, Readycode offramp, Transaction history, Account | none |
## Behavior resolves at runtime, from three inputs
What an instance does is not baked into the build. It resolves on load from ramp configuration, the region's compliance rules, and the partner's inbound session. Change the region or the session and watch the effective experience change.
- **Ramp configuration**: What the app **is**
- **Compliance configuration**: What the region allows
- **Inbound transaction**: What the partner wants now
The Ramp configuration input is fixed: Cash buy, Debit buy, Sell, Send, History. The other two change with the chosen region and session; the table states every combination.
| Region | Session | Compliance configuration | Inbound transaction | Effective session |
| --- | --- | --- | --- | --- |
| Standard region | Open session | Cash buy, Debit buy, Sell, Send, Standard disclosures | Amount open, Currency open, Destination open | In a standard region every rail the ramp permits stays available. The session is open, so the user chooses amount, currency, and destination. |
| Standard region | Partner pre-fill | Cash buy, Debit buy, Sell, Send, Standard disclosures | Amount $100 · locked, BTC · locked, Wallet pinned | In a standard region every rail the ramp permits stays available. The partner pre-filled a $100 BTC purchase and pinned the destination wallet, so those fields arrive locked. |
| Restricted region | Open session | Cash buy, Debit buy (removed), Sell, Send, State disclosure added | Amount open, Currency open, Destination open | In this restricted region compliance removes the debit rail and adds a state-specific disclosure, layered on top of the base config. The session is open, so the user chooses amount, currency, and destination. |
| Restricted region | Partner pre-fill | Cash buy, Debit buy (removed), Sell, Send, State disclosure added | Amount $100 · locked, BTC · locked, Wallet pinned | In this restricted region compliance removes the debit rail and adds a state-specific disclosure, layered on top of the base config. The partner pre-filled a $100 BTC purchase and pinned the destination wallet, so those fields arrive locked. |
None of this variation lives in a branch inside a flow; it is data the engine reads at load.
## The span it covers
The flows together cover the whole path a unit of value travels: onto a network, across it, and back off. Deliberately the entire path, not a single segment of it.
The path, in order:
1. **Acquire** (Onramp): Cash at retail, debit and card, kiosk
2. **Move** (Network): Send and receive, custodial or self-custody
3. **Convert out** (Offramp): ATM cash pickup, Readycode
- **Across jurisdictions**: Every U.S. state and every country in the footprint is expressed as data, not code. Entering a market is configuration and content, not a rebuild.
- **Across languages**: User-facing content is delivered separately from the code, so a new language reaches a ramp without a new build.
\* Localization delivery and per-ramp language sets are shipped; the breadth of any given ramp's language set is a configuration choice.
## The same engine runs anywhere
Three placements, one Orchestrator codebase. Standalone on its own domain, embedded in a partner's website, or embedded in a native app through a WebView.
- **Standalone**: A hosted ramp on its own domain, as Coinme's own consumer experiences ship.
- **Web app**: Loaded in an iframe inside a partner's site.
- **Native app**: Loaded in a WebView (iOS, Android, React Native) inside a partner's mobile app.
### Native apps are hybrid apps over the platform
A native app on the platform is a native shell hosting an embedded Orchestrator across the bridge, with the transactional core supplied rather than rebuilt. A family of distinct native apps is not a family of distinct transactional codebases: they differ by **configuration**, by **theming**, and by whatever each one chooses to build natively. This is hybrid app development augmented by a platform that supplies the hardest, most regulated part: web3 onramps, offramps, and the transacting in between.
## Two ways to embed
A spectrum from tight and real-time to simple and backend-driven. Pick the one that matches a partner's engineering shape.
### Messaging Bridge: tight and real-time
A postMessage channel with a handshake and continuous, two-way communication. Orchestrator auto-detects its host (iOS WKWebView, Android WebView, React Native, or web iframe). This is what enables configuration that changes mid-session and an event stream so the host always knows where the user is. The choice when the integration should feel seamless.
### Bridge Proxy: simple and backend-driven
A server-side REST pattern. The partner's backend posts a configuration and receives a widget URL with a short-lived token; the frontend just loads that URL. No postMessage handlers, no bridge protocol. The choice for backend-heavy teams who want the smallest possible frontend footprint.
### Side by side
| Capability | Messaging Bridge | Bridge Proxy |
| --- | --- | --- |
| Real-time, two-way channel | **Yes** | Backend webhooks only |
| Mid-session config changes | **Yes** | Fixed for the widget URL |
| Frontend integration work | Required | **Minimal** |
\* Both are real options with real tradeoffs. The Proxy has no client-side channel, so the frontend cannot directly know when a user is done; the Bridge provides that at the cost of integration work.
## Almost everything is a package
The platform is decomposed into independently versioned units, each delivered in the format native to where it is consumed. The same package serves two masters: an external SDK and internal composition.
| Surface | Package format | What it is |
| --- | --- | --- |
| JS / TS surfaces | `npm` | The JavaScript and React SDKs, including the host-side SDK that embeds the widget on the web. |
| iOS bridge | `SPM` | A Swift package, pulled the same way as any native dependency. |
| Android bridge | `Gradle` | A Kotlin library, in the native ecosystem's own manager. |
- **One package, two consumers**: The same artifact serves a bespoke partner build as a piece of an SDK and a composed product as one of its parts. A fix benefits every consumer at once. The packaging is the reuse.
- **The SDK is the same code**: The partner-facing SDKs are built from the same parts the platform uses. Using one capability and using the whole platform are points on a continuum, not different products.
## Themable today
Components read design tokens from a resolved theme rather than hardcoding values. Supply one accent token and the platform threads it everywhere. Try it.
A partner supplies a partial theme: only the tokens they want to change. Everything else resolves to the Coinme default through a deep merge. For embedded ramps, the session chooses light or dark through `theme` in its configuration; individual tokens are not part of that payload.
The page's live preview applies one brand accent token, chosen from preset swatches or any custom colour. Accent threads through the header, the card edge, the button, and the pill from a single token.
\* Design token theming is shipped. Logos, background images, brand strings and custom fonts are not part of it.
## The whole payoff, in one line
**Configuration, not code.** When behavior lives in data the engine reads at runtime, growth stops being an engineering project in the common case.
- **A new partner** is a configuration payload, not a fork of an application.
- **A new market** is compliance configuration and content, not a rebuild.
- **A new language** is a translation set, not a rebuild.
- **A new app** is a selection of existing flows under the same engine.
- **The result**: One Orchestrator codebase supports an open-ended number of application variants.
## Compliance and security travel with it
Two properties inherited automatically rather than integrated per partner.
- **Compliance is a platform property**: Jurisdictional rules are configuration and content, not branches in flow code. Jurisdiction rules and disclosures are maintained by Coinme and apply to your users automatically.
- **Approved hosts only**: The widget only runs inside hosts Coinme has approved for your ramp. Ask your Coinme integration contact to add your hosts.
This overview sits above the system-specific documents, each authoritative for its own area.
---
---
title: "One widget runs the whole customer experience."
url: "https://platformdocs.coinme.com/#/explainers/orchestrator"
markdown: "https://platformdocs.coinme.com/pages/explainers/orchestrator.md"
summary: "Orchestrator is the application behind the Coinme Widget. It runs everything your customer does with Coinme, from identity verification to buying, selling and sending, as one experience. What it offers is set by your Ramp, a configuration Coinme sets up for you and identifies by a Ramp ID. A Ramp is a configuration, not a codebase. Pick one below and watch the same widget become a different application."
---
# One widget runs the whole customer experience.
Orchestrator is the application behind the Coinme Widget. It runs everything your customer does with Coinme, from identity verification to buying, selling and sending, as one experience. What it offers is set by your **Ramp**, a configuration Coinme sets up for you and identifies by a Ramp ID. A Ramp is a configuration, not a codebase. Pick one below and watch the same widget become a different application.
## The same widget, different ramps
The page opens with a ramp assembler: pick a ramp, choose a custody model and apply a region overlay, and the exposed flows change. It offers 3 example ramps, every one drawn from the one shared flow library below. The table states what each exposes.
| Ramp | Ramp ID | Flows in any custody model | Flows added only when custodial | About this ramp |
| --- | --- | --- | --- | --- |
| Coinme | `‹coinme ramp›` | KYC, GreenDot cash, Transact, Debit, Readycode, Transaction history, Discover, Account management, Payment methods, EDD | Swaps, Send, Receive, Wallet management † | Coinme's own consumer ramp, running on the platform as a tenant like any partner. A rich composition drawn from the same shared library, not a special case in the code. |
| Cash partner (illustrative) | `‹assigned per ramp›` | KYC, GreenDot cash, Transact, Readycode, Transaction history, Discover, Account management | Wallet management †, Send, Receive | A retail composition spanning cash buy, digital transact, cash pickup, and location discovery. Wallet management, send, and receive appear only while the ramp operates custodially; flip custody to watch them drop. |
| Digital partner (illustrative) | `‹assigned per ramp›` | KYC, Transact, Debit, Transaction history, Account management, Payment methods, EDD | Swaps, Send, Receive, Wallet management † | A buy and sell composition. Debit, payment methods, account management, and EDD stand regardless of custody; wallet management, swaps, send, and receive join only when the ramp operates custodially. |
Custody is a configuration choice: any ramp, including Coinme's, can operate custodially or non-custodially*. Wallet management, swaps, send, and receive apply to custodial operation.
\* Custodial partner ramps are not implemented at this time.
† Wallet management is in development.
### Region overlay
A region overlay is the compliance layer applied on top of the base ramp. Overlays only further restrict, never grant.
| Overlay | Effect |
| --- | --- |
| no cash onramp | Removes GreenDot cash from any ramp that exposes it. |
| no cash offramp | Removes Readycode from any ramp that exposes it. |
| no onboarding | Removes every flow. |
### The shared flow library
- KYC
- Transact
- Swaps, custodial only
- Send, custodial only
- Receive, custodial only
- GreenDot cash
- Debit
- Readycode
- Wallet management, custodial only, in development
- Transaction history
- Discover
- Account management
- Payment methods
- EDD
## Why it exists
If Coinme shipped a single use application, every new market, partner, or product would mean another codebase to build, staff, and keep in sync with the last one. Compliance logic, risk instrumentation, and transaction handling would need to be re-implemented or forked each time, and a fix in one place would not reach the others. This would be unsustainable.
Orchestrator changes what a new application costs. Different Ramps are different selections and configurations of the same flows running under the same engine. A custodial cash experience, a non-custodial digital experience, and the standalone Coinme app are not three codebases; they are three compositions. Adding a partner is, in the ideal case, authoring a configuration payload rather than forking an application. New product offerings are efforts at new flows, not new applications. Composability reduces cost, complexity, and time to market.
- **An application per need** (Before): A new partner or market is a new build: its own codebase, its own release train, its own copy of compliance and risk logic to maintain and drift from the others.
- **A configuration per need** (With Orchestrator): A new partner or market is a Ramp: a configuration resolved at runtime against a shared engine and a shared flow library. One fix to a flow reaches every Ramp that uses it.
## Configured per Ramp ID
Everything that makes your integration yours lives in your Ramp: the flows it offers, the regions, payment rails, assets and languages it supports, and its default theme. Coinme sets up your Ramp and gives you its Ramp ID. Your app passes your Ramp ID when it opens the widget, and the widget loads your Ramp from it. There is one path for every Ramp: Coinme runs its own consumer app on the platform as a Ramp like any partner.
1. **Your app opens the widget**: It passes your Ramp ID and the settings for this session.
2. **The widget loads your Ramp**: Your Ramp ID selects the configuration Coinme set up for you.
3. **Regional rules apply**: The rules for the customer's region can remove flows your Ramp offers. They never add one.
4. **Your flows open**: The customer sees only the flows your Ramp allows, starting with the one your app asked for.
5. **Your app hears back**: The widget tells your app what happens over the bridge, for as long as the session lasts.
## Two inputs shape each session
What the widget does for one customer in one session is not baked into a build. It comes from two inputs: one Coinme sets for your Ramp, and one your app sends each time it opens the widget.
| Input | What it defines | Who sets it |
| --- | --- | --- |
| Ramp configuration (set by Coinme) | What the application **is**: the flows, regions, rails, assets and languages your Ramp offers, and its default theme. The same for every session. | Coinme, agreed with you and keyed by your Ramp ID. |
| Session configuration (sent by you) | What you want for **this session**: a pre-filled amount or asset, locked fields, a wallet destination, where to start, the theme and language. Varies per session. | Your app, when it opens the widget and while the session runs. |
The regional rules sit between the two. They can only further restrict what your Ramp allows, never grant something it does not. Your session configuration then tailors one session within what remains, so nothing about a single session needs a change to your Ramp. [The configuration explainer](https://platformdocs.coinme.com/pages/explainers/configuration.md) covers them in more detail.
## It talks to your app through the bridge
The widget talks to your app through the bridge. Your app sends the widget its session configuration, and the widget sends your app events as the customer moves through it, such as a completed transaction or a request to close. The Widget SDKs for web, iOS and Android run the bridge for you.
[The bridge explainer](https://platformdocs.coinme.com/pages/explainers/bridges.md) compares the bridge with the Bridge Proxy. [Build](https://platformdocs.coinme.com/pages/build/index.md#bridge) walks through the bridge sequence and the configuration fields.
## One codebase. Many applications.
**The economic fact.** Because a Ramp is configuration resolved at runtime, the platform's reach comes from composition rather than from more code.
- **Deployment**: **One** widget serves every Ramp.
- **Ramps**: **Many**, each a distinct application, all sharing the same flow library and engine.
- **New ramp**: A **configuration** exercise. No rebuild, no redeploy to stand one up.
- **First-party**: Coinme runs its own app on the platform as a **Ramp** like any partner. One path serves first-party and partner alike.
## Getting your ramp
Coinme sets up your Ramp, confirms it in our staging environment, and gives you its Ramp ID. Setting one up is a configuration exercise on our side; there is nothing for you to build or deploy.
1. **Agree what it offers**: Decide with your Coinme integration contact which flows, regions, assets and languages your Ramp offers, and how it looks.
2. **Coinme sets it up**: Coinme configures your Ramp and confirms it in our staging environment.
3. **You receive its Ramp ID**: Pass it whenever your app opens the widget.
This overview sits above the system-specific documents, each authoritative for its own area. Capabilities noted as in development are marked as such and should not be read as present state.
---
---
title: "What a user can do is composed, not coded."
url: "https://platformdocs.coinme.com/#/explainers/configuration"
markdown: "https://platformdocs.coinme.com/pages/explainers/configuration.md"
summary: "Three inputs decide what any given person sees and can do in a session. None of them live in a branch inside the app. Change one input and the behavior changes with it, with no new build and no new code."
---
# What a user can do is composed, not coded.
Three inputs decide what any given person sees and can do in a session. None of them live in a branch inside the app. Change one input and the behavior changes with it, with no new build and no new code.
## Two sources, three inputs
Everything that shapes a session comes from one of two places, and resolves into three inputs the engine composes.
At session start the widget reads Coinme's remote configuration for your Ramp, keyed by the Ramp identifier. It carries two of the three inputs. The base Ramp config says what the Ramp offers to everyone. The compliance overlay says what a given region takes away or requires. The third input arrives from the embedding partner over the Bridge, and it describes what this one session is for. Orchestrator composes all three and offers the user exactly the capabilities that survive.
| Source | About the source | Inputs it yields |
| --- | --- | --- |
| Remote configuration (SOURCE · KEYED BY RAMP ID) | Static for the ramp. Maintained by Coinme. | INPUT 1 · BASE RAMP CONFIG: What the Ramp offers everyone. INPUT 2 · COMPLIANCE OVERLAY: What a region takes away. |
| Bridge / Bridge Proxy (SOURCE · FROM THE PARTNER) | Delivered per session or transaction. | INPUT 3 · SESSION INTENT: What this session is for. |
**Orchestrator** composes all three inputs into: What the user can do.
- **What the Ramp offers** (Input 1 · Base config): The flows, rails, payment methods, assets, regions, and languages a Ramp exposes by default, to everyone, regardless of where they are. Source: **Coinme's remote configuration for your Ramp**. Same for every session of the Ramp.
- **What a region requires or removes** (Input 2 · Compliance): Region-matched rules layered on top of base config: excluded rails, excluded assets, required consents and disclosures, receipt formats. Source: **Coinme's remote configuration for your Ramp**. Applies to the user's region after identity verification.
- **What this session is for** (Input 3 · Session): Pre-filled amounts and assets, locked fields, a destination wallet, a language. The one input that differs between two people at once. Source: **The partner**, over the Bridge. Changing it: a new session.
These three inputs are a curated subset of what the platform can do. The configuration surface exposes the settings a Ramp needs to select and shape existing flows, rails, assets, and rules. The platform holds more capability than any single config payload names, and configuration chooses from it.
## Compose it yourself
Set the three inputs on the left. The panel on the right resolves what a user in this session can actually do, and shows how each input contributed.
On the page this is an interactive sandbox. The full set of input combinations is too large to list, so the tables below give each input on its own, then what every region and direction resolve to with the full base config and an open session, then what a requested asset and a narrower base config change.
### Input 1 · Base Ramp config (Remote configuration)
What this Ramp offers everyone. Toggle a capability off and no region can bring it back.
By default the base config offers every rail and asset below.
| Rails | Direction |
| --- | --- |
| Buy with cash | `buy` |
| Buy with card | `buy` |
| Sell for cash | `sell` |
| Sell to card | `sell` |
| Send crypto | `transfer` |
| Receive crypto | `transfer` |
Assets: `POL`, `BTC`, `ETH`, `USDC`.
### Input 2 · Compliance overlay (Remote configuration)
The user's region. Its rules can only take away from what base offers or add steps before the user proceeds, and they apply only after identity verification. The regions here are illustrative.
Each region the sandbox offers, with the full base config:
| Resolved region | Removes | Assets they can pick | Gates before they proceed | What it means |
| --- | --- | --- | --- | --- |
| None yet (before identity verification) | none | None until identity verification completes | none | Until the user completes identity verification, the only available action is verifying, and no regional rules apply yet. |
| Unrestricted region | none | POL, BTC, ETH, USDC | none | A region with no rules of its own. Base config passes through in full: nothing is removed and nothing is added. |
| Region A | Buy with cash, Sell for cash | POL, BTC, ETH, USDC | none | Removes cash buy and cash sell. Card rails and transfers still work. |
| Region B | ETH | POL, BTC, USDC | none | Removes one asset. A session that requests it meets a notice before the flow opens. |
| Region C | none | POL, BTC, ETH, USDC | One-time consent (once, before the app opens), Disclosure on every transaction (per transaction) | Removes nothing. The user accepts a one-time consent before the app opens and sees a disclosure on every transaction. |
| Region not in this Ramp | none | None | none | The Ramp is not offered in this region, so no regional rules are evaluated and the Ramp does not operate here. |
### Input 3 · Session intent (Bridge)
What the partner sends for this one session. It focuses and locks; it never grants.
Each option, what it adds to the session pins, and the RampConfig fields it sets. Every payload also carries `partnerId`. With nothing set the session reads: Open session. The user chooses everything.
| Session option | This session pins | RampConfig fields it sets |
| --- | --- | --- |
| Direction: User chooses | none | none |
| Direction: Buy | Direction: buy | none |
| Direction: Sell | Direction: sell | `destinationCurrency: "USD"` |
| Requested asset: User chooses | none | none |
| Requested asset: POL | Asset: POL | `destinationCurrency: "POL"` |
| Requested asset: BTC | Asset: BTC | `destinationCurrency: "BTC"` |
| Requested asset: ETH | Asset: ETH | `destinationCurrency: "ETH"` |
| Requested asset: USDC | Asset: USDC | `destinationCurrency: "USDC"` |
| Pins: Pre-fill $100 | Amount: $100 | `sourceAmount: 100`, `sourceCurrency: "USD"` |
| Pins: Lock fields | Fields locked | `sourceAmountLock: true`, `destinationCurrencyLock: true`, `walletLock: true` |
| Pins: Wallet provided | Wallet provided | `walletAddress` |
### What the user ends up with
Every region against every direction, with the full base config and no asset requested. "Shown as unavailable" lists what base offers but the user cannot use here.
| Resolved region | Direction | Status | Available to this user | Shown as unavailable | Outcome |
| --- | --- | --- | --- | --- | --- |
| None yet (before identity verification) | Any | Identity verification required: Nothing transacts until identity verification completes | Complete identity verification | Buy with cash, Buy with card, Sell for cash, Sell to card, Send crypto, Receive crypto | Until the user completes identity verification, the only available action is verifying. Nothing transacts and no regional rules apply yet. |
| Unrestricted region | User chooses | This user can transact | Buy with cash, Buy with card, Sell for cash, Sell to card, Send crypto, Receive crypto | none | |
| Unrestricted region | Buy | This user can transact | Buy with cash, Buy with card | none | |
| Unrestricted region | Sell | This user can transact | Sell for cash, Sell to card | none | |
| Region A | User chooses | This user can transact | Buy with card, Sell to card, Send crypto, Receive crypto | Buy with cash, Sell for cash | |
| Region A | Buy | This user can transact | Buy with card | Buy with cash, Sell for cash | |
| Region A | Sell | This user can transact | Sell to card | Buy with cash, Sell for cash | |
| Region B | User chooses | This user can transact | Buy with cash, Buy with card, Sell for cash, Sell to card, Send crypto, Receive crypto | none | |
| Region B | Buy | This user can transact | Buy with cash, Buy with card | none | |
| Region B | Sell | This user can transact | Sell for cash, Sell to card | none | |
| Region C | User chooses | This user can transact | Buy with cash, Buy with card, Sell for cash, Sell to card, Send crypto, Receive crypto | none | |
| Region C | Buy | This user can transact | Buy with cash, Buy with card | none | |
| Region C | Sell | This user can transact | Sell for cash, Sell to card | none | |
| Region not in this Ramp | Any | Ramp does not operate here: Region not offered by this Ramp | Nothing available. Ramp inactive in this region | none | |
### Requesting an asset
A requested asset is checked against the region before direction. Only regions that remove an asset are listed; elsewhere a request only adds the asset to the session pins.
| Resolved region | Requested asset | Lock fields | Status | Result |
| --- | --- | --- | --- | --- |
| Region B | ETH | no | Session blocked · asset not permitted: A notice before the flow opens | ETH is not permitted in Region B. The user clears the notice and picks a different asset. |
| Region B | ETH | yes | Session blocked · asset not permitted: A notice before the flow opens | ETH is not permitted in Region B. Because the session locks the asset, the user is returned to the partner app. |
| Region B | POL | no | This user can transact | Buy with cash, Buy with card, Sell for cash, Sell to card, Send crypto, Receive crypto |
### Narrowing the base config
Representative base edits. A region rule for a rail that base does not offer has no effect.
| Base offers | Resolved region | Direction | Status | Available to this user | Assets they can pick | Region rules with no effect | Outcome |
| --- | --- | --- | --- | --- | --- | --- | --- |
| Rails: Send crypto, Receive crypto. Assets: POL, BTC, ETH, USDC | Unrestricted region | User chooses | View-only (transaction history): No transacting rail survives for this path | Send crypto, Receive crypto | POL, BTC, ETH, USDC | 0 | No transacting rail survives, so the app opens to transaction history, view-only. |
| Rails: Send crypto, Receive crypto. Assets: POL, BTC, ETH, USDC | Unrestricted region | Buy | View-only (transaction history): No transacting rail survives for this path | View-only, no transacting | POL, BTC, ETH, USDC | 0 | Every buy rail is excluded here, so the session lands on transaction history, view-only. |
| Rails: Buy with cash, Buy with card, Sell for cash, Sell to card, Send crypto, Receive crypto. Assets: none | Unrestricted region | User chooses | This user can transact | Buy with cash, Buy with card, Sell for cash, Sell to card, Send crypto, Receive crypto | No assets available | 0 | |
| Rails: Buy with card, Sell to card, Send crypto, Receive crypto. Assets: POL, BTC, ETH, USDC | Region A | User chooses | This user can transact | Buy with card, Sell to card, Send crypto, Receive crypto | POL, BTC, ETH, USDC | 2 | |
## Why it is shaped this way
Every session sits where four different demands meet. The configuration model exists to satisfy all four at once, without a code branch for any of them.
Coinme operates in many jurisdictions, and the rules differ between them. At the same time the platform powers many partners, each wanting a different integration, and each of their customers arrives with a different transaction in mind. The combination of partners, jurisdictions, and transactions is far too large to maintain as branches in code, so the variation is expressed as configuration the engine reads at runtime. Each of the four demands lands in a specific place, and one platform serves every partner without forking.
### The four demands, and where each one lands
| The demand | What it pushes for | Where it lands |
| --- | --- | --- |
| What the platform can do | The full set of flows, rails, and assets that could ever be offered | **The capability ceiling**, above config |
| What a partner wants from their integration | A specific selection and look for their own Ramp | **Base Ramp config** (Input 1) |
| What a jurisdiction obligates and allows | Required disclosures, restricted rails and assets, receipt content | **Compliance overlay** (Input 2) |
| What a partner wants for one transaction | A pre-set, focused session for their inbound customer | **Inbound RampConfig** (Input 3) |
These pull in different directions. A partner wants flexibility, a jurisdiction sets limits, and a transaction wants a single narrow path. Expressing the demands as layered configuration is what lets one platform apply the rules a region sets and leave room where a partner needs it, in the same deployment, at the same moment.
## The whole model in one line
**Base config, narrowed by region, tailored per session.**
Each phrase answers a different demand, in the order they compose. Together they are how a heavily regulated business sells into many jurisdictions and many partners from a single platform.
- **Applied for you**: Jurisdiction rules and disclosures are maintained by Coinme and apply to your users automatically.
- **Flexible without forking**: Partners select and shape from shared parts. A new market or a new partner is a configuration effort, not a new codebase.
- **No release on your side**: When a regional rule changes, Coinme updates your Ramp's configuration. Your integration stays as it is.
## The real interface
The controls above map onto real shapes. Two of them are worth separating by name.
The Ramp's remote configuration is Inputs 1 and 2. It defines what the Ramp is, it is keyed by Ramp ID, and Coinme maintains it for your Ramp. The inbound **transaction** RampConfig is Input 3. It defines what a single session is for. The partner sends it over the Bridge when their customer comes inbound, and it can only focus and lock the capabilities the first two already allow. It cannot switch a flow on, add a rail, or reach into another partner's session. The first table below describes the kinds of regional rule Coinme can apply, which partners never author; the second is the inbound RampConfig partners send.
### Regional rules · what a region can apply on top of base config (Input 2)
| Rule | What it does to a user in that region |
| --- | --- |
| Region match | Which region the rules apply to, matched against the user's region after identity verification. |
| Removed rails | Ways to buy, sell, or move crypto that are not offered in the region. They drop out of the choices the user sees. |
| Removed assets | Assets not offered in the region. A session that requests one meets a notice before the flow opens. |
| One-time consents | Disclosures the user accepts once before the app opens. |
| Transaction disclosures | Disclosures shown before the user confirms a transaction, on some transactions or on every one. |
| Receipt content | Region-specific content on the user's receipt. It changes what the receipt says, not what the user can do. |
| Additional verification | Extra identity checks a region requires before the user can transact. |
### RampConfig · the inbound, per-session payload the partner sends over the Bridge (Input 3)
| Field | What it does to this session |
| --- | --- |
| `partnerId` | Identifies the embedding partner for this session. |
| `destinationCurrency` | The asset the session targets, for example **POL** for a buy. A value of **USD** resolves the direction to sell; anything else is a buy. |
| `sourceAmount` / `sourceCurrency` | Pre-fills the amount and paying currency so the user starts partway through. |
| `sourceAmountLock` / `destinationCurrencyLock` / `walletLock` | Locks a pre-filled field so the user cannot change it. |
| `walletAddress` | A destination wallet, which lets the flow skip asking the user for one. |
Regions and rules on this page are illustrative. The rules that apply in a given state are set by Coinme and can change.
---
---
title: "Features that travel."
url: "https://platformdocs.coinme.com/#/explainers/flows"
markdown: "https://platformdocs.coinme.com/pages/explainers/flows.md"
summary: "The Coinme Widget is made of flows. A flow is one complete part of the customer experience, such as identity verification, buying with a debit card, sending, or transaction history. Your Ramp decides which flows run. You never build or host a flow yourself."
---
# Features that travel.
The Coinme Widget is made of flows. A flow is one complete part of the customer experience, such as identity verification, buying with a debit card, sending, or transaction history. **Your Ramp decides which flows run.** You never build or host a flow yourself.
## What a flow is
A flow owns one complete feature from start to finish: its screens, its steps, and the work it does with Coinme behind them. Flows are built and run by Coinme inside the widget; your app never loads one directly.
Because each flow is complete on its own, the same flow behaves the same way in every Ramp that includes it. A Ramp is what you get when the widget puts several flows together into one experience.
A strip under this prose shows identity verification, location discovery, buy & sell and transaction history, with an arrow labelled "compose" pointing to "a Ramp".
## Which flows run
Your Ramp's configuration decides which flows the widget offers your customers. The rules for a customer's region can remove some of them, never add one. [The Orchestrator explainer](https://platformdocs.coinme.com/pages/explainers/orchestrator.md) shows how a Ramp comes together.
Your app chooses only where a session starts, with `flowId` in the configuration it sends. It defaults to the buy flow; `landing` opens home, where your Ramp decides what renders, and `transactionHistory` opens the transaction history. The full field list is on [Build](https://platformdocs.coinme.com/pages/build/index.md#config).
## The flow catalogue
| Flow | What it does |
| --- | --- |
| Identity Verification | Verifies who the customer is before they transact. |
| Location Discovery | Finds locations where a user can transact to buy or sell. |
| Transaction History | Lets a user retrieve their transaction history. |
| Cash at Retail | Buy crypto with cash at participating retail locations. |
| Digital Buy & Sell | Buy and sell using debit cards. |
| Cash Buy & Sell | Buy and sell using cash at ATM machines. |
| Send & Receive | Send and receive assets. |
Which of these your customers see depends on your Ramp and their region. Ask your Coinme integration contact which flows your Ramp offers.
## One flow, every Ramp
**Why it matters.** Because a flow is complete and composable, it is written and tested once and then reused wherever it fits. The same KYC flow serves many Ramps and partner integrations with identical behaviour, and a fix in the flow reaches every Ramp that uses it.
- **Speed**: New Ramps are assembled from existing flows in days rather than built from scratch.
- **Consistency**: A flow used in many Ramps gives every one the same behaviour and user experience.
- **Quality**: Each flow is tested once and reused with confidence.
- **The shape of it**: Build a capability once as a flow, then compose it into as many Ramps as the platform needs. The unit of work is the feature, and the feature is portable.
This overview sits above the system documents, each authoritative for its own area.
---
---
title: "Two ways to embed the widget."
url: "https://platformdocs.coinme.com/#/explainers/bridges"
markdown: "https://platformdocs.coinme.com/pages/explainers/bridges.md"
summary: "The right choice depends on what you want your integration to do. The bridge keeps a live channel open between your app and the widget. The proxy opens no channel: it loads a fixed configuration as a URL and reports back through backend webhooks. This page lays out what that difference means, so you can pick the one that fits your goals."
---
# Two ways to embed the widget.
The right choice depends on what you want your integration to do. The **bridge** keeps a live channel open between your app and the widget. The **proxy** opens no channel: it loads a fixed configuration as a URL and reports back through backend webhooks. This page lays out what that difference means, so you can pick the one that fits your goals.
## The two integration styles, one session each
The page opens with a mode switch between the two styles and a session tape for each, drawn between your app and the widget. The switch also changes the page: with the proxy selected, the first section shows the proxy's costs and benefits instead of the bridge's capabilities, and the bridge-only sections are hidden. Both versions are given here.
### With the bridge
Link from **Your app** to **Widget**: live channel.
| Step | Kind | What happens |
| --- | --- | --- |
| 1 | user | Buy BTC |
| 2 | event | purchased → your app |
| 3 | user | Buy ETH |
| 4 | event | done → your app |
↻ one session, channel stays open
**Bridge.** A live channel stays open, so the user never leaves context. They can transact, return, and transact again, and your app sees each step as it happens.
### With the proxy
Link from **Your app** to **Widget**: no channel.
| Step | Kind | What happens |
| --- | --- | --- |
| 1 | load | Load configured URL |
| 2 | user | Buy BTC |
| 3 | end | Session ends |
no channel back; results via backend webhooks
**Proxy.** The frontend loads a configured URL with no channel back. Your app hears what it can through backend webhooks, and cannot tell on its own when the user is done.
## What the bridge allows
### With the bridge
The bridge allows direct, real-time communication between your app and the Coinme widget. This real-time bi-directional communication allows tight integration between your application and the widget, dissolving the user experience boundary so the two feel like one app. The removal of this boundary enables integrations that are not possible with the bridge proxy.
- **The user never loses context**: Your app and the widget share one live session, so the user moves between them with no stops, reloads, or re-entry. The integration feels like a single app, not a handoff to a separate page.
- **Repeat transactions, light on the backend**: In the same open session the user can buy, return, and buy again. The bridge carries this on the client, so multi-transaction flows do not require new backend infrastructure.
- **Live events, both ways**: Each action reaches your app the moment it happens, including when the user has finished and wants to return to your app.
### With the proxy
With the proxy selected, this section is titled **Bridge Proxy: costs and benefits**.
The proxy is the same widget delivered a different way. Your backend creates a configured instance over REST and returns a URL your frontend loads. Choosing it is a trade, so here are both sides.
| Side | Title | Detail |
| --- | --- | --- |
| Gain | What you gain | A familiar integration model. The proxy is standard REST and an iframe or webview: your backend authenticates, configures the instance, and returns a URL. There is no client-side protocol to learn, and configuration stays on the backend, where a backend-oriented team already works. |
| Give up | What you give up | The tooling. The iOS and Android packages, the ready-made WebView, the handshake, the transport, and the regulatory and permissions coverage all apply to bridge integrations. With the proxy you load the URL yourself and own that surface. The live channel, and the capabilities that come with it: context preservation, repeat transactions without backend work, and live events. Your app hears back only through backend webhooks, and cannot tell on its own when the user is done. |
Where it fits: the proxy suits backend-heavy teams that prefer to keep integration on the backend and have limited frontend capacity. When there is frontend capacity to use the packages, the bridge is usually the lower-effort path rather than the higher one, and it keeps the capabilities above.
## Hybrid app architecture out of the box
Shown only with the bridge selected; the proxy view hides this section.
A hybrid app is a native shell hosting web content with a channel between them. That channel is the bridge. It is built on the standard pieces every platform already provides: a script message handler on iOS, a message listener on Android, `onMessage` in a React Native WebView, and `window.postMessage` to an iframe on the web.
The Coinme bridge is that same channel with a defined message set: a handshake to open the session, then messages to configure the widget, mount a flow, and listen for events. It is a well-understood pattern, and you do not have to assemble it yourself.
| Platform | Native channel | With the Coinme bridge |
| --- | --- | --- |
| iOS | WKScriptMessageHandler + WKWebView | The same bridge channel, into a **WKWebView**. |
| Android | WebView message listener | The same bridge channel, into an **Android WebView**. |
| React Native | WebView onMessage / postMessage | The same bridge channel, into a **React Native WebView**. |
| Web | window.postMessage to an iframe | The same bridge channel, into an **iframe**, via framekit. |
## We provide the tooling
Shown only with the bridge selected; the proxy view hides this section.
### You do not implement the channel by hand.
The iOS, Android, React Native* and JS packages give you a ready-made bridge. Drop the package into your application and you get a ready-made view and bridge session that is ready to use.
- **WebView**: Created and configured for you, with the requirements already met.
- **Handshake**: Opened and acknowledged automatically. You wait for a ready session, nothing more.
- **Transport**: The right channel for the platform is detected and wired up.
- **Security**: The embedding requirements are satisfied by the package on setup.
- **Regulatory & permissions**: The packages carry the regulatory and permissions requirements the integration must meet, so your build satisfies them out of the box. You do not have to implement or own that surface.
You plug it in and send transactions.
\* These packages are in active development. Availability and interfaces may change before general release.
## When each fits
Both approaches put the widget in an iframe or WebView. The difference is whether a channel stays open, and that follows from what you need your app to know and do.
The **proxy** opens no channel. Your backend sets the configuration once, hands the frontend a URL to load, and receives what it can through backend webhooks. The picture is narrower: your frontend cannot tell when the user has finished and wants to return, so you trap navigation to detect it. Choose the proxy when the embed is static and backend-only, and server-side webhooks are enough.
The **bridge** keeps the channel open. Choose it when the experience depends on the user moving between your app and the widget without friction, or on your app knowing in real time what the user is doing.
## Side by side
| Axis | Bridge | Proxy |
| --- | --- | --- |
| Session | Stays open, many transactions | One load, one transaction |
| Getting started | Drop in one of our packages | Point an iframe or webview at a URL |
| Between transactions | Nothing, the session continues | Mint a new URL |
| Live config updates | **Yes**, mid-session | No, fixed at mint time |
| How your app hears back | Live events on the client & backend webhooks | Backend webhooks only |
| Knowing the user is done | Delivered as an event | Not available; trap navigation |
| Other events | Delivered in real time | Not available |
| Where config is transmitted | Client, sent live | Server, baked into the URL |
| Best when | The experience should feel seamless, or repeat transactions matter | The embed is static and server-side webhooks are enough |
## Events and actions over the bridge
Shown only with the bridge selected; the proxy view hides this section.
The widget sends your app events as the customer moves through it, such as a completed transaction, a cash order ready to resume, or a request to close. Every Widget SDK delivers the same typed events, and [the event catalogue](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) is the contract. Coinme configures which events reach your app and under what names; ask your Coinme integration contact for the ones you need.
Your app can send the widget the documented host actions, such as a new configuration to start the next transaction (see [the bridge on Build](https://platformdocs.coinme.com/pages/build/index.md#bridge)). The widget decides what each one does and ignores anything else.
Orchestrator is the embedded transaction engine. The bridge is the live channel between your app and that engine. The proxy delivers a fixed configuration as a URL.
---
---
title: "FAQs"
url: "https://platformdocs.coinme.com/#/explainers/faq"
markdown: "https://platformdocs.coinme.com/pages/explainers/faq.md"
summary: "Questions that come up while reading the explainers or trying the demo apps, answered in a paragraph or two."
---
# FAQs
Questions that come up while reading the explainers or trying the demo apps, answered in a paragraph or two.
## What does simulated transaction mode mean?
In simulated transaction mode the widget runs its full path without moving real funds. Crypto transactions are real operations on testnets, so the chain activity is genuine even though no actual funds move. Card transactions use test cards. Barcodes are generated but cannot be redeemed.
The surrounding data is not simulated. Locations shown in the apps are real locations, and the regulatory rules the widget applies reflect real jurisdictional requirements.
## Are the demo apps available world-wide?
No. Because of regulation, the demo apps and the live web demo are not available from sanctioned or otherwise restricted jurisdictions. Jurisdictions currently affected include, but are not limited to:
- Afghanistan
- Belarus
- Central African Republic
- Congo
- Côte d'Ivoire
- Cuba
- Ghana
- Iran
- Iraq
- Lebanon
- Liberia
- Libya
- Nicaragua
- Nigeria
- North Korea
- Palestine
- Russian Federation
- Somalia
- Sudan
- Syria
- Ukraine
- Venezuela
- Yemen
- Zimbabwe
Answers describe the platform as it ships today. When behavior changes, the answer changes with it.
---
---
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.
## Widget SDKs
### Web: An iframe you own.
Framekit. One React component or a plain script. Your page's origin is the trust boundary.
```tsx
```
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)
## 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).
## 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.
## 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.
## 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.
## 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)
---
---
title: "Every SDK. Every document."
url: "https://platformdocs.coinme.com/#/build/library"
markdown: "https://platformdocs.coinme.com/pages/build/library.md"
summary: "One entry per SDK; each holds all of its documents, from the overview to the interface reference. Narrow by family, platform or document type, or just type."
---
# Every SDK. Every document.
One entry per SDK; each holds all of its documents, from the overview to the interface reference. Narrow by family, platform or document type, or just type.
The Library lists 25 SDKs in 7 families, with 107 distinct documents between them. 17 of them have an agent skill; Prove onboarding API client (`@coinme/prove-onboarding-api-client`), Quotes API client (`@coinme/quotes-api-client`), Transactions API client (`@coinme/transactions-api-client`), History API client (`@coinme/history-api-client`), Locations API client (`@coinme/locations-api-client`), Send API client (`@coinme/send-api-client`), Custody API client (`@coinme/custody-api-client`), Cash ramp API client (`@coinme/cash-ramp-api-client`) have none yet.
## Widget SDK
Embed the complete Coinme Widget in your app: buy, sell, cash, KYC, all inside one session.
### Framekit (Web)
The widget in an iframe you own. React component or plain script.
- **Package**: `@coinme/coinme-bridge-framekit`
- **Agent skill**: [coinme-widget-web](https://platformdocs.coinme.com/skills/coinme-widget-web/SKILL.md)
- [Embed Coinme Widget with Framekit](https://platformdocs.coinme.com/pages/build/web/overview.md) (Overview)
- [How it works](https://platformdocs.coinme.com/pages/build/web/how-it-works.md) (Guide)
- [How to use](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) (Quick start)
- [Doctor](https://platformdocs.coinme.com/pages/build/web/doctor.md) (Tooling)
- [CoinmeConfig fields](https://platformdocs.coinme.com/pages/build/index.md#config) (Reference)
- [Bridge events](https://platformdocs.coinme.com/pages/explainers/bridges.md#events) (Reference)
### CoinmeBridge for iOS (iOS)
A view controller you present or embed. One long-lived session, a four-method delegate.
- **Package**: `CoinmeBridge · Swift`
- **Agent skill**: [coinme-widget-ios](https://platformdocs.coinme.com/skills/coinme-widget-ios/SKILL.md)
- [The widget, inside your app](https://platformdocs.coinme.com/pages/build/native/ios/overview.md) (Overview)
- [Quick start for iOS](https://platformdocs.coinme.com/docs/ios-quick-start.md) (Quick start)
- [Integration guide](https://platformdocs.coinme.com/docs/ios-integration-guide.md) (Guide)
- [Patterns](https://platformdocs.coinme.com/pages/build/native/ios/patterns.md) (Guide)
- [CoinmeConfig fields](https://platformdocs.coinme.com/pages/build/index.md#config) (Reference)
- [CoinmeEvent cases](https://platformdocs.coinme.com/pages/build/native/ios/how-it-works.md) (Reference)
### CoinmeBridge for Android (Android)
A fragment you host. Same config, same events, a listener instead of a delegate.
- **Package**: `CoinmeBridge · Kotlin`
- **Agent skill**: [coinme-widget-android](https://platformdocs.coinme.com/skills/coinme-widget-android/SKILL.md)
- [The widget, inside your app](https://platformdocs.coinme.com/pages/build/native/android/overview.md) (Overview)
- [Quick start for Android](https://platformdocs.coinme.com/docs/android-quick-start.md) (Quick start)
- [Integration guide](https://platformdocs.coinme.com/docs/android-integration-guide.md) (Guide)
- [Patterns](https://platformdocs.coinme.com/pages/build/native/android/patterns.md) (Guide)
- [CoinmeConfig fields](https://platformdocs.coinme.com/pages/build/index.md#config) (Reference)
- [CoinmeEvent classes](https://platformdocs.coinme.com/pages/build/native/android/how-it-works.md) (Reference)
## Risk SDK
Stream device, connection and behavioural signal to the risk engine so your transactions are approved.
### Risk SDK for Web (Web)
Set up the engine at start, tag flows and elements, fetch a session tag before transacting.
- **Package**: `@coinme-security/risk-sdk-js`
- **Agent skill**: [coinme-risk-web](https://platformdocs.coinme.com/skills/coinme-risk-web/SKILL.md)
- [Coinme Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) (Overview)
- [Using the Risk SDK for Web](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md) (Guide)
- [Functions: setup, update, tag, getSessionTag](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md#api-reference) (Reference)
- [FlowType](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md#flow-types) (Reference)
### Risk SDK for iOS (iOS)
Behavioural and device signal from native iOS apps.
- **Package**: `CoinmeRisk · Swift`
- **Agent skill**: [coinme-risk-ios](https://platformdocs.coinme.com/skills/coinme-risk-ios/SKILL.md)
- [Coinme Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) (Overview)
- [Risk SDK for iOS native apps](https://platformdocs.coinme.com/docs/risk-sdk-for-ios-native-apps.md) (Guide)
- [FlowType](https://platformdocs.coinme.com/docs/risk-sdk-for-ios-native-apps.md#flowtype-options) (Reference)
### Risk SDK for Android (Android)
Behavioural and device signal from native Android apps.
- **Package**: `CoinmeRisk · Kotlin`
- **Agent skill**: [coinme-risk-android](https://platformdocs.coinme.com/skills/coinme-risk-android/SKILL.md)
- [Coinme Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) (Overview)
- [Risk SDK for Android native apps](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md) (Guide)
- [FlowType](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md#flowtype-options) (Reference)
### Risk SDK for React Native (React Native)
The web SDK's surface with native device collectors.
- **Package**: `@coinme-security/risk-sdk-react-native`
- **Agent skill**: [coinme-risk-react-native](https://platformdocs.coinme.com/skills/coinme-risk-react-native/SKILL.md)
- [Coinme Risk SDK](https://platformdocs.coinme.com/docs/coinme-risk-sdk.md) (Overview)
- [Risk SDK for React Native](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md) (Guide)
- [Expo support](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md#expo-support) (Guide)
- [API reference](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md#api-reference) (Reference)
## Vault SDK
Capture card numbers and billing details in hosted fields. Raw values never touch your code.
### Vault SDK for JavaScript (Web)
Hosted card fields for any web stack. createCoinmeVault, five field factories, submitPaymentMethod.
- **Package**: `@coinme-security/vault-sdk-js`
- **Agent skill**: [coinme-vault-js](https://platformdocs.coinme.com/skills/coinme-vault-js/SKILL.md)
- [Coinme Vault SDK](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md) (Overview)
- [Vault SDK for JavaScript](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md) (Guide)
- [Framework setup: React, Vue, SSR](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md#framework-setup) (Guide)
- [Secure fields and options](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md#secure-fields) (Reference)
- [CoinmeVaultError kinds](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md#error-handling) (Reference)
- [examples/vanilla, examples/react](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md#example-apps) (Sample app)
- [Transient Auth Token (backend)](https://platformdocs.coinme.com/docs/transient-auth-token.md) (Guide)
### Vault SDK for iOS (iOS)
Hosted card capture in native iOS.
- **Package**: `CoinmeVault · Swift`
- **Agent skill**: [coinme-vault-ios](https://platformdocs.coinme.com/skills/coinme-vault-ios/SKILL.md)
- [Coinme Vault SDK](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md) (Overview)
- [Vault SDK for iOS native](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md) (Guide)
- [Error handling](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md#error-handling) (Reference)
- [Transient Auth Token (backend)](https://platformdocs.coinme.com/docs/transient-auth-token.md) (Guide)
### Vault SDK for Android (Android)
Hosted card capture in native Android.
- **Package**: `CoinmeVault · Kotlin`
- **Agent skill**: [coinme-vault-android](https://platformdocs.coinme.com/skills/coinme-vault-android/SKILL.md)
- [Coinme Vault SDK](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md) (Overview)
- [Vault SDK for Android native](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md) (Guide)
- [Error handling](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md#error-handling) (Reference)
- [Transient Auth Token (backend)](https://platformdocs.coinme.com/docs/transient-auth-token.md) (Guide)
### Vault SDK for React Native (React Native)
Hosted card capture for React Native apps.
- **Package**: `@coinme-security/vault-sdk-react-native`
- **Agent skill**: [coinme-vault-react-native](https://platformdocs.coinme.com/skills/coinme-vault-react-native/SKILL.md)
- [Coinme Vault SDK](https://platformdocs.coinme.com/docs/coinme-vault-sdk.md) (Overview)
- [Vault SDK for React Native](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-react-native.md) (Guide)
- [Transient Auth Token (backend)](https://platformdocs.coinme.com/docs/transient-auth-token.md) (Guide)
## Onboarding SDK
Onboard a new customer and take them through non-documentary KYC. The SSN goes into a hosted field; your code never sees it.
### Onboarding SDK for JavaScript & React (Web)
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.
- **Package**: `@coinme-security/onboarding-sdk-react`
- **Agent skill**: [coinme-onboarding-react](https://platformdocs.coinme.com/skills/coinme-onboarding-react/SKILL.md)
- [Coinme Onboarding SDK](https://platformdocs.coinme.com/docs/coinme-onboarding-sdk.md) (Overview)
- [Onboarding SDK for JavaScript & React](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) (Guide)
- [Form examples](https://platformdocs.coinme.com/docs/onboarding-sdk-examples.md) (Sample app)
- [Quickstart: the drop-in form](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#quickstart) (Quick start)
- [CustomerOnboardingForm props](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#drop-in-form) (Reference)
- [Headless React: provider, fields, hook](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#headless-react) (Reference)
- [Phone verification](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#phone-verification) (Reference)
- [Core API](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#core-api-without-react) (Reference)
- [CoinmeOnboardingError kinds](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#error-handling) (Reference)
- [Commonly asked questions](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md#commonly-asked-questions) (Guide)
- [Example: linking onboarding to your backend session](https://platformdocs.coinme.com/docs/onboarding-sdk-session-example.md) (Guide)
- [Transient Auth Token (backend)](https://platformdocs.coinme.com/docs/transient-auth-token.md) (Guide)
### Onboarding SDK for React Native (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.
- **Package**: `@coinme-security/onboarding-sdk-react-native`
- **Agent skill**: [coinme-onboarding-react-native](https://platformdocs.coinme.com/skills/coinme-onboarding-react-native/SKILL.md)
- [Coinme Onboarding SDK](https://platformdocs.coinme.com/docs/coinme-onboarding-sdk.md) (Overview)
- [Onboarding SDK for React Native](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) (Guide)
- [Quickstart: the drop-in form](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#quickstart) (Quick start)
- [Expo and bare React Native](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#expo-and-bare-react-native) (Guide)
- [CustomerOnboardingForm props](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#drop-in-form) (Reference)
- [Headless React Native: provider, fields, hook](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#headless-react-native) (Reference)
- [Phone verification](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#phone-verification) (Reference)
- [Core API](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#core-api) (Reference)
- [CoinmeOnboardingError kinds](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#error-handling) (Reference)
- [Commonly asked questions](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md#commonly-asked-questions) (Guide)
- [Transient Auth Token (backend)](https://platformdocs.coinme.com/docs/transient-auth-token.md) (Guide)
## Compliance SDK
Apply Coinme's regional compliance rules in your own screens: where Coinme operates, what a region excludes, which consents and disclosures to show, and a record of what the customer accepted. Advisory: Coinme's backend still enforces every rule.
### Compliance SDK for JavaScript & React (Web)
Coinme's jurisdictions, rule helpers, localized consent and disclosure copy, and attestations, as a framework-agnostic core with React bindings.
- **Package**: `@coinme-security/compliance-sdk-react`
- **Agent skill**: [coinme-compliance-react](https://platformdocs.coinme.com/skills/coinme-compliance-react/SKILL.md)
- [Coinme Compliance SDK](https://platformdocs.coinme.com/docs/coinme-compliance-sdk.md) (Overview)
- [Compliance SDK for JavaScript & React](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) (Guide)
- [Quickstart: a state picker](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#quickstart) (Quick start)
- [An end-to-end integration](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#putting-it-together-an-end-to-end-integration) (Guide)
- [The configuration client](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#the-configuration-client) (Reference)
- [Region helpers](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#regions) (Reference)
- [Transaction rules](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#transaction-rules) (Reference)
- [Consents and disclosures](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#consents-and-transactional-disclosures) (Reference)
- [Localized copy and safe rendering](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#localized-copy) (Reference)
- [Attestations](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#attestations) (Reference)
- [CoinmeComplianceError kinds](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#error-handling) (Reference)
- [Commonly asked questions](https://platformdocs.coinme.com/docs/compliance-sdk-react.md#commonly-asked-questions) (Guide)
### Compliance SDK for React Native (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.
- **Package**: `@coinme-security/compliance-sdk-react-native`
- **Agent skill**: [coinme-compliance-react-native](https://platformdocs.coinme.com/skills/coinme-compliance-react-native/SKILL.md)
- [Coinme Compliance SDK](https://platformdocs.coinme.com/docs/coinme-compliance-sdk.md) (Overview)
- [Compliance SDK for React Native](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) (Guide)
- [Quickstart: a state picker](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#quickstart) (Quick start)
- [The platform: storage and app state](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#the-platform) (Reference)
- [Provider and hooks](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#provider-and-hooks) (Reference)
- [Regions and rules](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#regions-and-rules) (Reference)
- [Localized copy](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#localized-copy) (Reference)
- [Rendering the copy natively](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#render-it-natively) (Reference)
- [Attestations](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#attestations) (Reference)
- [Consents and disclosures, end to end](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#putting-it-together-consents-and-disclosures) (Guide)
- [CoinmeComplianceError kinds](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#error-handling) (Reference)
- [Commonly asked questions](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md#commonly-asked-questions) (Guide)
## CaaS API clients
Typed convenience methods for the Coinme-as-a-Service API, and a foundation for the backend your web and mobile apps call. They handle tokens, environments and errors.
### Core API client (Server)
Authentication with AuthService, supported crypto currencies and their chains, and historical market data.
- **Package**: `@coinme/core-api-client`
- **Agent skill**: [coinme-caas-api-clients](https://platformdocs.coinme.com/skills/coinme-caas-api-clients/SKILL.md)
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-core-api-client.md) (Reference)
- [Authenticate](https://platformdocs.coinme.com/docs/caas-api-clients.md#authenticate) (Guide)
- [Environments](https://platformdocs.coinme.com/docs/caas-api-clients.md#environments) (Reference)
- [Errors](https://platformdocs.coinme.com/docs/caas-api-clients.md#errors) (Reference)
- [Upgrading from 1.x](https://platformdocs.coinme.com/docs/caas-api-clients.md#upgrading-from-1-x) (Guide)
- [Transient Auth Token (backend)](https://platformdocs.coinme.com/docs/transient-auth-token.md) (Guide)
### Prove onboarding API client (Server)
Phone verification, identity prefill and verification, and customer onboarding.
- **Package**: `@coinme/prove-onboarding-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-prove-onboarding-api-client.md) (Reference)
### Quotes API client (Server)
Transactional and informational quotes, and transaction limits.
- **Package**: `@coinme/quotes-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-quotes-api-client.md) (Reference)
### Transactions API client (Server)
Buy and sell, with or without a quote, sell all, and the blockchain id of a sell funded from an external wallet.
- **Package**: `@coinme/transactions-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-transactions-api-client.md) (Reference)
### History API client (Server)
Asset balances, transaction history and a single transaction.
- **Package**: `@coinme/history-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-history-api-client.md) (Reference)
### Locations API client (Server)
The jurisdictions Coinme is licensed in.
- **Package**: `@coinme/locations-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-locations-api-client.md) (Reference)
### Send API client (Server)
Sending to an external wallet.
- **Package**: `@coinme/send-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-send-api-client.md) (Reference)
### Custody API client (Server)
Not yet published. Customer wallets, network fee estimates, sends and your enterprise balances.
- **Package**: `@coinme/custody-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-custody-api-client.md) (Reference)
### Cash ramp API client (Server)
Not yet published. Cash locations and order templates.
- **Package**: `@coinme/cash-ramp-api-client`
- **Agent skill** none yet
- [CaaS API clients](https://platformdocs.coinme.com/docs/caas-api-clients.md) (Overview)
- [Methods and types](https://platformdocs.coinme.com/docs/caas-cash-ramp-api-client.md) (Reference)
## Wallet addresses
Check that a wallet address is well-formed for its asset and chain before you store it or send to it. Offline and format-only, it needs no Coinme credentials and works with the Widget and with Coinme-as-a-Service.
### Wallet address validator (Web)
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.
- **Package**: `@coinme/wallet-address-validator`
- **Agent skill**: [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md)
- [Wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md) (Guide)
- [Quickstart](https://platformdocs.coinme.com/docs/wallet-address-validator.md#quickstart) (Quick start)
- [Recommended integration](https://platformdocs.coinme.com/docs/wallet-address-validator.md#recommended-integration) (Guide)
- [API: validateAddress, isSupported, errors](https://platformdocs.coinme.com/docs/wallet-address-validator.md#api) (Reference)
- [Chains and chainType](https://platformdocs.coinme.com/docs/wallet-address-validator.md#chains-and-chaintype) (Reference)
- [Address formats worth knowing](https://platformdocs.coinme.com/docs/wallet-address-validator.md#address-formats-worth-knowing) (Reference)
- [Supported assets and chains](https://platformdocs.coinme.com/docs/wallet-address-validator-supported-assets.md) (Reference)
- [Commonly asked questions](https://platformdocs.coinme.com/docs/wallet-address-validator.md#commonly-asked-questions) (Guide)
## Testing
Fake identities for testing Coinme KYC, which work in the Widget and in Coinme onboarding for CaaS, plus test accounts and expected behavior in the stage Widget.
### Widget stage testing
Create fully verified test customers with fake identities that pass Coinme KYC in stage, and know what to expect in the stage Widget.
- [Creating Widget test accounts in stage](https://platformdocs.coinme.com/docs/widget-test-accounts.md) (Guide)
- [Test identities for Coinme KYC](https://platformdocs.coinme.com/docs/widget-test-identities.md) (Reference)
- [Expected behavior in stage](https://platformdocs.coinme.com/docs/widget-stage-behavior.md) (Guide)
---
---
title: "SDK versions"
url: "https://platformdocs.coinme.com/#/build/versions"
markdown: "https://platformdocs.coinme.com/pages/build/versions.md"
summary: "The current release of every Coinme SDK, generally available or in beta, and the SDKs still in development. Install the version listed here: it is the one this site documents."
---
# SDK versions
The current release of every Coinme SDK, generally available or in beta, and the SDKs still in development. Install the version listed here: it is the one this site documents.
## Generally available
Each SDK's current release, as its package registry or repository publishes it. The guides and the agent skills name the same version.
| SDK | Family | Surface | Platform | Package | Version | Peer dependencies |
| --- | --- | --- | --- | --- | --- | --- |
| [Framekit](https://platformdocs.coinme.com/pages/build/web/overview.md) | Widget SDK | Widget / Ramp integration | Web | `@coinme/coinme-bridge-framekit` | **1.1.2** | `react` >=18.0.0, `react-dom` >=18.0.0 |
| [CoinmeBridge for iOS](https://platformdocs.coinme.com/pages/build/native/ios/overview.md) | Widget SDK | Widget / Ramp integration | iOS | `CoinmeBridge` · Swift | **1.3.0** | none |
| [CoinmeBridge for Android](https://platformdocs.coinme.com/pages/build/native/android/overview.md) | Widget SDK | Widget / Ramp integration | Android | `CoinmeBridge` · Kotlin | **1.3.0** | none |
| [Risk SDK for Web](https://platformdocs.coinme.com/docs/using-the-coinme-risk-sdk-for-web.md) | Risk SDK | Coinme-as-a-Service (CaaS) integration | Web | `@coinme-security/risk-sdk-js` | **1.2.0** | none |
| [Risk SDK for iOS](https://platformdocs.coinme.com/docs/risk-sdk-for-ios-native-apps.md) | Risk SDK | Coinme-as-a-Service (CaaS) integration | iOS | `CoinmeRisk` · Swift | **1.1.2** | none |
| [Risk SDK for Android](https://platformdocs.coinme.com/docs/risk-sdk-for-android-native-apps.md) | Risk SDK | Coinme-as-a-Service (CaaS) integration | Android | `CoinmeRisk` · Kotlin | **1.1.2** | none |
| [Risk SDK for React Native](https://platformdocs.coinme.com/docs/coinme-risk-sdk-for-react-native.md) | Risk SDK | Coinme-as-a-Service (CaaS) integration | React Native | `@coinme-security/risk-sdk-react-native` | **1.1.0** | `react` >=18, `react-native` >=0.72 |
| [Vault SDK for JavaScript](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-javascript.md) | Vault SDK | Coinme-as-a-Service (CaaS) integration | Web | `@coinme-security/vault-sdk-js` | **1.3.0** | none |
| [Vault SDK for iOS](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-ios-native.md) | Vault SDK | Coinme-as-a-Service (CaaS) integration | iOS | `CoinmeVault` · Swift | **1.0.1** | none |
| [Vault SDK for Android](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-android-native.md) | Vault SDK | Coinme-as-a-Service (CaaS) integration | Android | `CoinmeVault` · Kotlin | **1.0.0** | none |
| [Vault SDK for React Native](https://platformdocs.coinme.com/docs/coinme-vault-sdk-for-react-native.md) | Vault SDK | Coinme-as-a-Service (CaaS) integration | React Native | `@coinme-security/vault-sdk-react-native` | **1.3.0** | `@vgs/collect-react-native` ^1.1.6, `react` >=18, `react-native` >=0.76 |
| [Onboarding SDK for JavaScript & React](https://platformdocs.coinme.com/docs/onboarding-sdk-react.md) | Onboarding SDK | Coinme-as-a-Service (CaaS) integration | Web | `@coinme-security/onboarding-sdk-react` | **1.7.1** | `react` >=18, `react-dom` >=18 |
| [Onboarding SDK for React Native](https://platformdocs.coinme.com/docs/onboarding-sdk-react-native.md) | Onboarding SDK | Coinme-as-a-Service (CaaS) integration | React Native | `@coinme-security/onboarding-sdk-react-native` | **1.2.1** | `@vgs/collect-react-native` ^1.1.6, `react` >=18, `react-native` >=0.76 |
| [Wallet address validator](https://platformdocs.coinme.com/docs/wallet-address-validator.md) | Wallet addresses | Both integrations (Widget / Ramp and CaaS) | Web | `@coinme/wallet-address-validator` | **1.2.0** | none |
## Beta
Published and installable, but not generally available yet: the interface can still change and not all functionality is guaranteed. You can use one in development builds but check with your Coinme integration contact before taking it to production.
| SDK | Family | Surface | Platform | Package | Version | Peer dependencies |
| --- | --- | --- | --- | --- | --- | --- |
| [Compliance SDK for JavaScript & React](https://platformdocs.coinme.com/docs/compliance-sdk-react.md) | Compliance SDK | Coinme-as-a-Service (CaaS) integration | Web | `@coinme-security/compliance-sdk-react` | **1.1.3** (beta) | `react` >=18, `react-dom` >=18 |
| [Compliance SDK for React Native](https://platformdocs.coinme.com/docs/compliance-sdk-react-native.md) | Compliance SDK | Coinme-as-a-Service (CaaS) integration | React Native | `@coinme-security/compliance-sdk-react-native` | **1.0.2** (beta) | `react` >=18, `react-native` >=0.79 |
## In development
These SDKs have no release yet. Their pages describe the version that is coming; don't take them to production.
| SDK | Family | Platform | Package | Status |
| --- | --- | --- | --- | --- |
| [Core API client](https://platformdocs.coinme.com/docs/caas-core-api-client.md) | CaaS API clients | Server | `@coinme/core-api-client` | Not published yet: version 2.0.0 is next. The registry still serves the deprecated 1.x. |
| [Prove onboarding API client](https://platformdocs.coinme.com/docs/caas-prove-onboarding-api-client.md) | CaaS API clients | Server | `@coinme/prove-onboarding-api-client` | Not published yet: version 2.0.0 is next. The registry still serves the deprecated 1.x. |
| [Quotes API client](https://platformdocs.coinme.com/docs/caas-quotes-api-client.md) | CaaS API clients | Server | `@coinme/quotes-api-client` | Not published yet: version 2.0.0 is next. The registry still serves the deprecated 1.x. |
| [Transactions API client](https://platformdocs.coinme.com/docs/caas-transactions-api-client.md) | CaaS API clients | Server | `@coinme/transactions-api-client` | Not published yet: version 2.0.0 is next. The registry still serves the deprecated 1.x. |
| [History API client](https://platformdocs.coinme.com/docs/caas-history-api-client.md) | CaaS API clients | Server | `@coinme/history-api-client` | Not published yet: version 2.0.0 is next. The registry still serves the deprecated 1.x. |
| [Locations API client](https://platformdocs.coinme.com/docs/caas-locations-api-client.md) | CaaS API clients | Server | `@coinme/locations-api-client` | Not published yet: version 2.0.0 is next. The registry still serves the deprecated 1.x. |
| [Send API client](https://platformdocs.coinme.com/docs/caas-send-api-client.md) | CaaS API clients | Server | `@coinme/send-api-client` | Not published yet: version 2.0.0 is next. The registry still serves the deprecated 1.x. |
| [Custody API client](https://platformdocs.coinme.com/docs/caas-custody-api-client.md) | CaaS API clients | Server | `@coinme/custody-api-client` | Not published yet: new with the 2.0.0 release of the CaaS API clients, starting at 0.1.0. |
| [Cash ramp API client](https://platformdocs.coinme.com/docs/caas-cash-ramp-api-client.md) | CaaS API clients | Server | `@coinme/cash-ramp-api-client` | Not published yet: new with the 2.0.0 release of the CaaS API clients, starting at 0.1.0. |
## How this list stays current
This list is checked against each package registry every weekday.
The same list as JSON, one entry per SDK with its family, surface, platform, package, version or status, and peer dependency ranges: [versions.json](https://platformdocs.coinme.com/versions.json).
---
---
title: "Build with an agent"
url: "https://platformdocs.coinme.com/#/build/agents"
markdown: "https://platformdocs.coinme.com/pages/build/agents.md"
summary: "Every page on this site is also published as plain Markdown from the same source, so a coding agent can read the real guides rather than a summary. Point it at the index, tell it what you are building, and it has what it needs, apart from the credentials only Coinme can give you."
---
# Build with an agent.
Every page on this site is also published as plain Markdown from the same source, so a coding agent can read the real guides rather than a summary. Point it at the index, tell it what you are building, and it has what it needs, apart from the credentials only Coinme can give you.
## Pick the integration first
Coinme has two ways to build, and nearly every skill below belongs to exactly one of them. Which one the human is on decides which skills apply, so settle it before choosing a skill: [the agent primer](https://platformdocs.coinme.com/agents/primer.md) has the decision tree, and [Two ways to build on Coinme](https://platformdocs.coinme.com/agents/surfaces.md) the side-by-side comparison.
- **Widget / Ramp integration** (`surface: "ramp"`). For transactional partners: a partner that wants regulated crypto buying and selling inside its own product without building it. The end user is onboarded as a Coinme customer, inside the widget. Sign-in, KYC, payment and receipts all happen in the Coinme Widget. Skills: [coinme-widget-web](https://platformdocs.coinme.com/skills/coinme-widget-web/SKILL.md), [coinme-widget-ios](https://platformdocs.coinme.com/skills/coinme-widget-ios/SKILL.md), [coinme-widget-android](https://platformdocs.coinme.com/skills/coinme-widget-android/SKILL.md). It needs none of the Onboarding, Vault or Risk SDKs and no CaaS API calls: the widget does sign-in, KYC, payment and risk inside its frame.
- **Coinme-as-a-Service (CaaS) integration** (`surface: "caas"`). For partners with their own user base and their own application, who want Coinme to perform regulated services for those users. The end users are the partner's customers. Coinme onboards them to CaaS and verifies them (KYC) as a service, and returns a `customerId`, but they are not Coinme consumer users and never see a Coinme app. Skills: [coinme-onboarding-react](https://platformdocs.coinme.com/skills/coinme-onboarding-react/SKILL.md), [coinme-onboarding-react-native](https://platformdocs.coinme.com/skills/coinme-onboarding-react-native/SKILL.md), [coinme-compliance-react](https://platformdocs.coinme.com/skills/coinme-compliance-react/SKILL.md), [coinme-compliance-react-native](https://platformdocs.coinme.com/skills/coinme-compliance-react-native/SKILL.md), [coinme-risk-web](https://platformdocs.coinme.com/skills/coinme-risk-web/SKILL.md), [coinme-risk-ios](https://platformdocs.coinme.com/skills/coinme-risk-ios/SKILL.md), [coinme-risk-android](https://platformdocs.coinme.com/skills/coinme-risk-android/SKILL.md), [coinme-risk-react-native](https://platformdocs.coinme.com/skills/coinme-risk-react-native/SKILL.md), [coinme-vault-js](https://platformdocs.coinme.com/skills/coinme-vault-js/SKILL.md), [coinme-vault-ios](https://platformdocs.coinme.com/skills/coinme-vault-ios/SKILL.md), [coinme-vault-android](https://platformdocs.coinme.com/skills/coinme-vault-android/SKILL.md), [coinme-vault-react-native](https://platformdocs.coinme.com/skills/coinme-vault-react-native/SKILL.md), [coinme-caas-api-clients](https://platformdocs.coinme.com/skills/coinme-caas-api-clients/SKILL.md). There is no widget, so no `rampId`, `partnerKey`, widget URL or embed allowlist: those belong to the Widget / Ramp integration only.
- **Both integrations (Widget / Ramp and CaaS)** (`surface: "both"`). Skills for an SDK that works the same on either integration and uses neither one's credentials or services, so it adds to whichever the human is on: [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md).
Each skill's front matter, and its entry in `skills/index.json`, names its `surface`: `ramp`, `caas`, or `both` for a skill that applies on either. If the human is unsure which integration they have, ask them, or have them ask their Coinme integration contact.
## Point your agent at the docs
These are examples, one per platform, to adapt to what you are building. Each hands the agent a skill, or the skills index where an SDK has one skill per platform, and names the task; the skill carries the prerequisites, the code and how to check the result.
### Web: Widget SDK, Widget / Ramp integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-widget-web/SKILL.md to embed the Coinme widget in my web app with framekit. Ask me for the ramp id and partner key when you reach them.
```
### iOS: Widget SDK, Widget / Ramp integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-widget-ios/SKILL.md to integrate the Coinme widget into my iOS app with CoinmeBridge. Ask me for the registry token, the ramp id and the partner key when you reach them.
```
### Android: Widget SDK, Widget / Ramp integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-widget-android/SKILL.md to integrate the Coinme widget into my Android app with CoinmeBridge. Ask me for the registry token, the ramp id and the partner key when you reach them.
```
### React: Onboarding SDK, CaaS integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-onboarding-react/SKILL.md to add customer onboarding to my React app with the drop-in form. Ask me for the registry token and for how my backend will supply the transient auth token, which the Onboarding SDK's guides call the onboarding token.
```
### React Native: Onboarding SDK, CaaS integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-onboarding-react-native/SKILL.md to add customer onboarding to my React Native app with the drop-in form, on iOS and Android. Ask me for the registry token and for how my backend will supply the transient auth token, which the Onboarding SDK's guides call the onboarding token.
```
### React: Compliance SDK, CaaS integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-compliance-react/SKILL.md to apply Coinme's compliance rules in my React app with the Compliance SDK: offer only onboardable states, show and record the consents and disclosures a customer owes, and check each transaction before it reaches my backend. Ask me for the registry token and for how my backend will supply the transient auth token the attestation store sends.
```
### React Native: Compliance SDK, CaaS integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-compliance-react-native/SKILL.md to apply Coinme's compliance rules in my React Native app with the Compliance SDK, on iOS and Android: offer only onboardable states, show and record the consents and disclosures a customer owes, and check each transaction before it reaches my backend. Ask me for the registry token and for how my backend will supply the transient auth token the attestation store sends.
```
### Risk: Risk SDK, CaaS integration
```
Read the skills index at https://platformdocs.coinme.com/skills/index.json, pick the coinme-risk skill for my platform and follow it, so a session tag is ready before every transaction. Ask me for the registry token and the client ID when you reach them.
```
### Vault: Vault SDK, CaaS integration
```
Read the skills index at https://platformdocs.coinme.com/skills/index.json, pick the coinme-vault skill for my platform and follow it to add card capture and submit the payment method to Coinme. Ask me for the registry token and for how my backend will supply the transient auth token.
```
### Server: CaaS API clients, CaaS integration
```
Follow the skill at https://platformdocs.coinme.com/skills/coinme-caas-api-clients/SKILL.md to call the Coinme CaaS API from my Node.js backend with version 2 of the CaaS API clients. Ask me for the CaaS registry token, the partner ID, the client secret and the base URLs when you reach them.
```
## What the agent finds
The build that publishes this site also writes a Markdown rendition of it, generated from the same content the pages render, so the two cannot drift. The index lists every page with a one-line summary; each page carries its headings, prose, tables and code samples, with a short header naming the platform, the package and, for imported documents, the canonical source and its last update.
An agent that can fetch a URL needs nothing else. Those that read a site through its `llms.txt` convention find the index on their own; the page head also advertises it.
| File | What it holds |
| --- | --- |
| [llms.txt](https://platformdocs.coinme.com/llms.txt) | The index: every page with its title, a one-line summary and the link to its Markdown. |
| [llms-full.txt](https://platformdocs.coinme.com/llms-full.txt) | Every page in one file. It is large; most agents do better with the slice for their SDK. |
| `llms-.txt` | One SDK's pages and skills in one file: `llms-widget.txt`, `llms-risk.txt`, `llms-vault.txt`, `llms-onboarding.txt`, `llms-compliance.txt`, `llms-api.txt` and `llms-wallet.txt`. |
| `docs/.md` | One file per SDK document: the Risk, Vault, Onboarding and Compliance SDKs, the CaaS API clients, the wallet address validator, and the CoinmeBridge quick starts and guides. |
| `pages//.md` | The Build guides for the web, iOS and Android, and the explainers. |
| [skills/index.json](https://platformdocs.coinme.com/skills/index.json) | Every skill with its description, platform, package and version, and the URL of its `SKILL.md`. |
## What the agent cannot get on its own
These come from your Coinme integration contact, not from the docs. The agent will stop and ask for them; have them ready, and keep them out of the files it writes.
- **`COINME_REGISTRY_TOKEN`** (Registry): The registry token that installs the Coinme SDKs from the private registry: framekit, CoinmeBridge, the Onboarding, Compliance, Vault and Risk SDKs, and the wallet address validator. It belongs in an environment variable or a gitignored file, never in a commit.
- **`rampId`** (Widget): Which Ramp the widget loads. Issued at onboarding, with the environment it belongs to.
- **`partnerKey`** (Widget): Identifies your integration to the widget. Issued at onboarding alongside the ramp id.
- **`clientId`** (Risk SDK): Identifies your integration to the Risk Engine; the SDK refuses to initialise without it. Issued at onboarding, one per environment.
- **`transient auth token`** (Onboarding, Vault and Compliance SDKs): The 10-minute token your backend mints for each submit and hands to the page or app: it exchanges your API client ID and client secret for a partner access token, then calls Coinme's `browserAuth` endpoint. The Onboarding SDK and the Compliance SDK's attestation store send it through `getHeaders`; the Vault SDK as the `Authorization` header of the payment-method submit. Never pass the partner access token to any of them. The Compliance SDK's attestations are not available in the beta at this time. The agent can write the backend route; the client ID and secret are yours.
- **`partnerId / clientSecret`** (CaaS API clients): The partner credentials your backend exchanges for a CaaS API bearer token. One pair per environment, kept in your server's secret store and never in a browser or an app.
- **`COINME_CAAS_REGISTRY_TOKEN`** (CaaS API clients): The token that installs the CaaS API clients from their own registry. Like the SDK token, it belongs in an environment variable, never in a commit.
## Skills
The pages tell an agent what the platform is and how each SDK works. A skill tells it what to do: a procedure in the open Agent Skills format, with the prerequisites to check, the credentials to ask you for, the exact code in the right files, and how to verify the result. Each is generated from the same guides as the pages, so the two cannot disagree. Give your agent the URL, or drop the folder into your project where it keeps its skills.
- [coinme-widget-web](https://platformdocs.coinme.com/skills/coinme-widget-web/SKILL.md): Embeds the Coinme Widget in a web app with framekit: install, mount, events, live settings, Doctor checks.
- [coinme-widget-ios](https://platformdocs.coinme.com/skills/coinme-widget-ios/SKILL.md): Integrates the Coinme Widget into an iOS app with CoinmeBridge: package, config, view controller, delegate, session ready.
- [coinme-widget-android](https://platformdocs.coinme.com/skills/coinme-widget-android/SKILL.md): Integrates the Coinme Widget into an Android app with CoinmeBridge: dependency, config, fragment, listener, session ready.
- [coinme-onboarding-react](https://platformdocs.coinme.com/skills/coinme-onboarding-react/SKILL.md): Adds customer onboarding with non-documentary KYC to a React or JavaScript web app with the Onboarding SDK.
- [coinme-onboarding-react-native](https://platformdocs.coinme.com/skills/coinme-onboarding-react-native/SKILL.md): Adds customer onboarding with non-documentary KYC to a React Native or Expo app with the Onboarding SDK: install with its secure field peer, drop-in form or headless pieces, the onboarding token, error kinds, sandbox checks on both platforms.
- [coinme-compliance-react](https://platformdocs.coinme.com/skills/coinme-compliance-react/SKILL.md): Applies Coinme's compliance rules in a React or JavaScript web app with the Compliance SDK: provider, region status, rule helpers, localized consent and disclosure copy rendered safely, attestations after onboarding, and a checked transaction.
- [coinme-compliance-react-native](https://platformdocs.coinme.com/skills/coinme-compliance-react-native/SKILL.md): Applies Coinme's compliance rules in a React Native or Expo app with the Compliance SDK: the native platform and its storage, provider, region status, rule helpers, localized consent and disclosure copy rendered natively, attestations after onboarding, and disclosures before a transaction.
- [coinme-risk-web](https://platformdocs.coinme.com/skills/coinme-risk-web/SKILL.md): Adds the Risk SDK to a web app: install, set up the engine with your client ID, tag inputs, and get a session tag before each transaction.
- [coinme-risk-ios](https://platformdocs.coinme.com/skills/coinme-risk-ios/SKILL.md): Adds the Risk SDK to an iOS app: dependency, App Store disclosures, permissions, initialise, track inputs, submit before transactions.
- [coinme-risk-android](https://platformdocs.coinme.com/skills/coinme-risk-android/SKILL.md): Adds the Risk SDK to an Android app: dependency, Play requirements, permissions, ProGuard, initialise, track inputs, submit before transactions.
- [coinme-risk-react-native](https://platformdocs.coinme.com/skills/coinme-risk-react-native/SKILL.md): Adds the Risk SDK to a React Native or Expo app: native setup on both platforms, the fingerprint contract, tracked inputs, submit before transactions.
- [coinme-vault-js](https://platformdocs.coinme.com/skills/coinme-vault-js/SKILL.md): Adds card capture to a web app with the Vault SDK: secure fields, styling, validity, and submitting the payment method to Coinme with the transient auth token.
- [coinme-vault-ios](https://platformdocs.coinme.com/skills/coinme-vault-ios/SKILL.md): Adds card capture to an iOS app with the Vault SDK: package, configuration, fields, form state, and submitting with the transient auth token.
- [coinme-vault-android](https://platformdocs.coinme.com/skills/coinme-vault-android/SKILL.md): Adds card capture to an Android app with the Vault SDK: repository, dependency, fields in Kotlin, XML or Compose, and submitting with the transient auth token.
- [coinme-vault-react-native](https://platformdocs.coinme.com/skills/coinme-vault-react-native/SKILL.md): Adds card capture to a React Native or Expo app with the Vault SDK: provider, secure field components, hooks, and submitting with the transient auth token.
- [coinme-caas-api-clients](https://platformdocs.coinme.com/skills/coinme-caas-api-clients/SKILL.md): Calls the CaaS API from a Node.js backend with version 2 of the CaaS API clients: registry, AuthService, one client per area, environments, error handling and the move off 1.x.
- [coinme-wallet-address-validator](https://platformdocs.coinme.com/skills/coinme-wallet-address-validator/SKILL.md): Checks a wallet address for its asset and chain before your app stores it or sends to it, with the wallet address validator: strict mode, chainType for multi-chain assets, trimmed input and the three outcomes. Offline, for the Widget and CaaS alike.
---
---
title: "Embed Coinme Widget with Framekit."
url: "https://platformdocs.coinme.com/#/build/web"
markdown: "https://platformdocs.coinme.com/pages/build/web/overview.md"
summary: "This page demonstrates how the Coinme Widget can be embedded in a partner web application using the Coinme Framekit SDK."
surface: "ramp"
platform: "web"
package: "@coinme/coinme-bridge-framekit"
version: "1.1.2"
peerDependencies: {"react":">=18.0.0","react-dom":">=18.0.0"}
---
# Embed Coinme Widget with Framekit.
This page demonstrates how the Coinme Widget can be embedded in a partner web application using the Coinme Framekit SDK.
Framekit (`@coinme/coinme-bridge-framekit`) is the web counterpart to Coinme's iOS and Android bridges, which allow embedding into native apps.
All flows run inside the embedded frame. The live demo is not available in [sanctioned or otherwise restricted jurisdictions](https://platformdocs.coinme.com/pages/explainers/faq.md#sanctioned-jurisdictions) due to regulation.
On the site, this page runs the live Coinme Widget beside the text: a full Orchestrator deployment in an iframe, mounted with framekit's `CoinmeFrame`. A Markdown file cannot host the embed; [How to use](https://platformdocs.coinme.com/pages/build/web/how-to-use.md) has the code that puts it on a page and [How it works](https://platformdocs.coinme.com/pages/build/web/how-it-works.md) explains the bridge behind it.
---
---
title: "One iframe, one SDK, the whole ramp."
url: "https://platformdocs.coinme.com/#/build/web/how-it-works"
markdown: "https://platformdocs.coinme.com/pages/build/web/how-it-works.md"
summary: "The widget in this demo is a full Coinme Orchestrator deployment running in an iframe. Framekit (@coinme/coinme-bridge-framekit) is the TypeScript SDK that puts it there and keeps a secure, typed message channel, the bridge, open between the host app and the widget."
surface: "ramp"
platform: "web"
package: "@coinme/coinme-bridge-framekit"
version: "1.1.2"
peerDependencies: {"react":">=18.0.0","react-dom":">=18.0.0"}
---
# One iframe, one SDK, the whole ramp.
The widget in this demo is a full Coinme Orchestrator deployment running in an iframe. **Framekit** (@coinme/coinme-bridge-framekit) is the TypeScript SDK that puts it there and keeps a secure, typed message channel, the **bridge**, open between the host app and the widget.
The web isn't the only host. Coinme ships native bridge SDKs for **iOS** (CoinmeViewController, Swift) and **Android** (CoinmeFragment, Kotlin) that embed the same Orchestrator in a WebView using the same bridge mechanics: identical protocol, handshake, rampConfig payload, and events. Integrate once conceptually, and the ramp behaves the same in a web page or a native app.
## Three layers, three responsibilities
- **Owns the page** (Your app): Layout, branding, where the widget sits, and the CoinmeConfig it is given. Nothing crypto-related runs here.
- **Owns the plumbing** (Framekit): Creates the iframe, opens a locked-down postMessage channel, runs the handshake, ships config in, surfaces events out. No HTTP, no UI. Transport only.
- **Owns the experience** (Orchestrator): The entire ramp UI (auth, KYC, payments, receipts) plus its own API calls. A separate hosted deployment per environment.
## The bridge lifecycle
1. **Iframe construction**: Framekit creates an