Onramp hosting requirements

The Onramp widget renders inside a cross-origin iframe or popup served from a hosted origin on Arc. Configure your host page to meet the requirements on this page before deploying. For an end-to-end walkthrough that uses these settings, see the embed widget quickstart.

Endpoints

Onramp exposes two environments. Use sandbox for local development and testing. Use production for real transactions.

Endpoint	Sandbox	Production
Widget	`https://onramp-sandbox.arc.io`	`https://onramp.arc.io`
API	`https://api-test.circle.com`	`https://api.circle.com`

Your API key authenticates your server. Keep it server-side only, since it grants full access to your Onramp integration. Both createAppServerKit on your server and new AppKit on your client accept a widgetBaseUrl option that points at the widget origin. The default is the production widget URL, so production integrations don’t need to set it. To target sandbox, pass the sandbox widget origin on both sides. Server side:

const server = createAppServerKit({
  onramp: {
    apiKey: process.env.CIRCLE_API_KEY!,
    widgetBaseUrl: "https://onramp-sandbox.arc.io",
  },
});

Client side:

const kit = new AppKit({
  onramp: {
    widgetBaseUrl: "https://onramp-sandbox.arc.io",
  },
});

The server and client values must match. If they differ, mountIframe and openWindow throw an INPUT_WIDGET_URL_ORIGIN_MISMATCH error (code 1910).

Sandbox

Sandbox is a testing environment for developing your Onramp integration without real money movement. It exposes the same API surface as production. Only the endpoints and the API key binding differ. Use sandbox for local development. The production widget’s Content Security Policy blocks http://localhost, so a production widget won’t load from a local dev server over HTTP. Sandbox allows http://localhost:*. To target sandbox, override two config values on the server and one on the client. API keys are environment bound: use a sandbox API key with sandbox and a production API key with production.

Setting	Set on	Sandbox	Production
`apiKey`	server (`createAppServerKit`)	your sandbox API key	your production API key
`baseUrl`	server (`createAppServerKit`)	`https://api-test.circle.com`	`https://api.circle.com` (default)
`widgetBaseUrl`	server and client	`https://onramp-sandbox.arc.io`	`https://onramp.arc.io` (default)

Example `.env`

.env

# --- server-only secret ---
CIRCLE_API_KEY=YOUR_API_KEY

# --- sandbox ---
ONRAMP_BASE_URL=https://api-test.circle.com
NEXT_PUBLIC_ONRAMP_WIDGET_BASE_URL=https://onramp-sandbox.arc.io

# --- production ---
# ONRAMP_BASE_URL=https://api.circle.com
# NEXT_PUBLIC_ONRAMP_WIDGET_BASE_URL=https://onramp.arc.io

The widgetBaseUrl value is safe to expose to the browser, so a NEXT_PUBLIC_ (or your framework’s equivalent) prefix lets the client read it. The API key is the only real secret and never gets a public prefix.

Testing behavior

Sandbox doesn’t move real money. It sends testnet tokens instead. Use dummy data only. Never enter real PII.

Area	Sandbox behavior
Phone OTP	No SMS is sent. Any six-digit code passes. `000000` fails and keeps the challenge open for retries. Country prefixes such as `+44` need no special setup.
KYC identity	Photo verification is required, but doesn’t require a real ID. Any photo containing a human face passes.
Debit card	Don’t enter real card details.
Apple Pay / Google Pay	Follow the widget’s instructions. Your card isn’t charged.
Bank transfers	The bank transfer details page has a button to submit a test deposit. Test funds land in the destination wallet only on Ethereum.
Deposit events	Only `DEPOSIT_SUBMITTED` fires, with `settlementExpected: false`. `DEPOSIT_SETTLED` is defined in the SDK but isn’t emitted in sandbox. To verify a test deposit, check the destination wallet’s USDC balance on the configured blockchain’s block explorer.

The identity form’s required fields vary by region:

Region	Required fields
US	First name, last name, date of birth, email, address, state, ZIP code, 9-digit SSN.
Non-US	First name, last name, date of birth, email, address with a valid formatted postcode for the country, and a tax or national identifier (any letters or digits are accepted). A state or region is only required when the country lists one.

Content security policy

If your site sends a CSP header, you must allow the widget origin for the environment you target. Without this directive, the iframe silently fails to load. Sandbox:

frame-src https://onramp-sandbox.arc.io;

Production:

frame-src https://onramp.arc.io;

The widget handles its own requests through its CSP, so your page doesn’t need connect-src for Onramp. Other App Kit capabilities (Bridge, Swap, Earn, Borrow, Unified Balance) need connect-src https://api.circle.com for error reporting if used in the browser.

Container element

Two container-side preconditions apply when calling mountIframe:

The container must be attached to the document

The App Kit SDK appends the iframe synchronously and installs a MutationObserver that auto-disposes the widget if the container later detaches. The container must be in the DOM when you call mountIframe:

In React, mount from a useEffect (not during render) so the ref is populated before the call.
In other frameworks, use that framework’s mounted lifecycle.
In plain browser code, wait for DOMContentLoaded or insert the container yourself before calling.

The container must have an explicit, non-zero height

The iframe renders at width: 100%; height: 100%. A cross-origin iframe cannot size itself to its content, so without a resolved height the iframe collapses to 0px and the user sees nothing.

#onramp-root {
  height: 720px;
}

Any of these resolve the height correctly:

A fixed height (such as 720px).
A min-height.
A flex child inside a parent with a sized cross-axis.

When you use openWindow instead of mountIframe, the host environment matters:

Mobile browsers open a new tab, not a sized popup. The width and height features are ignored.
In-app browsers (Instagram, Facebook, TikTok, LinkedIn, WeChat, LINE) block popups. openWindow returns { status: 'blocked', reason: 'in_app_browser' } so you can fall back to mountIframe.
Installed web apps in standalone mode also block popups. openWindow returns { status: 'blocked', reason: 'pwa_standalone' }.

See Choose iframe or popup mode for the full fallback flow.

Event delivery requires embedding

Both mountIframe and openWindow deliver widget events to the page that called them. If you open the widget URL as a top-level page (for example, from a native app in Safari View Controller or Chrome Custom Tabs), nothing receives the events. Host the widget on your own page using one of these two modes and open that page instead.

Third-party storage in iOS Safari

iOS Safari’s Intelligent Tracking Prevention (ITP) can restrict the embedded app’s access to its own storage inside an iframe. If you see KYC or session issues that only occur on iOS Safari, use openWindow mode on that platform.

Session lifetime

Onramp sessions are valid for 30 minutes from creation. If your app pre-fetches or reuses a session, mint a fresh one once more than 30 minutes have passed to avoid a stale-session error.

Close unused widgets

Each mountIframe() call, and each successful openWindow() call, returns a widget controller. Keep that controller and call widget.close() before starting over or when the user leaves the view.

Send

Bridge

Swap

Unified Balance

Onramp

Earn

Borrow

Onramp hosting requirements

Endpoints

Widget origin

Sandbox

Example `.env`

Testing behavior

Content security policy

Container element

The container must be attached to the document

The container must have an explicit, non-zero height

Event delivery requires embedding

Third-party storage in iOS Safari

Session lifetime

Close unused widgets

​Endpoints

​Widget origin

​Sandbox

​Example .env

​Testing behavior

​Content security policy

​Container element

​The container must be attached to the document

​The container must have an explicit, non-zero height

​Popup mode constraints

​Event delivery requires embedding

​Third-party storage in iOS Safari

​Session lifetime

​Close unused widgets

Endpoints

Widget origin

Sandbox

Example `.env`

Testing behavior

Content security policy

Container element

The container must be attached to the document

The container must have an explicit, non-zero height

Popup mode constraints

Event delivery requires embedding

Third-party storage in iOS Safari

Session lifetime

Close unused widgets