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

<a id="environments"></a>

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

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

## 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 `<ENTITLEMENT_TOKEN>`.
- **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)

<a id="platform-requirements"></a>

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

<a id="go-live-checklists"></a>

## 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 <your deployed URL>` 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)

<a id="not-stated"></a>

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