Fiat and CEX on-ramp

Users without crypto can fund their account directly inside your app. The deposit service mints a signed Swapped checkout URL for a registered account; the user pays in Swapped’s hosted widget; the purchased crypto lands on the account and is processed like any other deposit — bridged to the account’s target and reported through the same status tracking.

How it works

Your backend requests a signed checkout URL for the user’s account.
You show the URL in an iframe or in-app browser.
The user completes payment (and KYC, when required) with Swapped.
You receive onramp-order webhooks as the order progresses.
Swapped sends the purchased crypto — currently USDC on Base — to the account. From here the standard pipeline takes over: the deposit is detected, bridged to the account’s target, and reported via the regular deposit webhooks.

Prerequisites

The account is registered — minting a checkout URL for an account that isn’t registered to your project returns 403 Unauthorized.
A webhook URL is configured if you want order updates pushed rather than polled.
Calls are made from your backend. The endpoints require your API key, which never ships in client-side code.

Mint a checkout URL

const DEPOSIT_SERVICE_URL =
    "https://v1.orchestrator.rhinestone.dev/deposit-processor";
const API_KEY = "YOUR_RHINESTONE_API_KEY";

const response = await fetch(`${DEPOSIT_SERVICE_URL}/onramp/swapped/widget-url`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
    body: JSON.stringify({
        smartAccount: "0xUSER_ACCOUNT_ADDRESS",
        baseCurrencyCode: "EUR",
        baseCurrencyAmount: 100,
        method: "apple-pay",
    }),
});

const { url, externalCustomerId, expiresAt } = await response.json();

Only smartAccount is required. The optional fields prefill the widget:

Field	Type	Description
`smartAccount`	`string`	The registered account that receives the crypto
`email`	`string`	Prefills the user’s email
`baseCountry`	`string`	User’s country (ISO 3166-1 alpha-2, e.g. `"DE"`)
`baseCurrencyCode`	`string`	Fiat currency to charge in (e.g. `"EUR"`)
`baseCurrencyAmount`	`number`	Prefilled purchase amount in the fiat currency
`locale`	`string`	Widget language
`method`	`string`	Preselected payment method: `"creditcard"`, `"apple-pay"`, or `"bank-transfer"`

The response carries the signed URL:

Field	Type	Description
`url`	`string`	The checkout URL to embed
`currencyCode`	`string`	Asset the purchase settles in, as `ASSET_NETWORK` (currently `"USDC_BASE"`)
`sandbox`	`boolean`	`true` when the service runs against Swapped’s sandbox
`externalCustomerId`	`string`	`<account>:<orderUuid>` — correlates the checkout with its webhooks
`expiresAt`	`string`	End of the order-tracking window (ISO 8601)

The URL is signed by the service, so its parameters — destination wallet and asset — can’t be modified client-side. Mint a fresh URL for each checkout session. The purchase always settles in the asset reported by currencyCode; when the account’s target differs, the bridge hop happens automatically. Full request and response schemas: POST /onramp/swapped/widget-url.

Fund from an exchange

To let users transfer from a centralized exchange balance (Binance, Coinbase, and others) instead of paying with fiat, mint a Connect URL. The request takes a subset of the widget fields — smartAccount plus optional baseCountry, baseCurrencyCode, locale, and a connection preselecting the exchange. There’s no amount or payment-method prefill; the user chooses those inside the exchange flow. The response shape is identical:

const response = await fetch(`${DEPOSIT_SERVICE_URL}/onramp/swapped/connect-url`, {
    method: "POST",
    headers: { "Content-Type": "application/json", "x-api-key": API_KEY },
    body: JSON.stringify({
        smartAccount: "0xUSER_ACCOUNT_ADDRESS",
        connection: "binance",
    }),
});

List the supported exchanges with GET /onramp/swapped/connect-exchanges; full schema at POST /onramp/swapped/connect-url. Embed the URL in an iframe with payment and camera permissions — Apple Pay and camera-based KYC need them:

<iframe src={url} allow="payment; camera; microphone; clipboard-write" />

In a mobile app, open the URL in an in-app browser (SFSafariViewController on iOS, Chrome Custom Tabs on Android) rather than a plain WebView — Apple Pay and camera access are restricted in bare WebViews. The URL carries no redirect or callback parameter. Detect completion through the onramp-order webhook or by polling order status, then dismiss the widget from your own UI.

A user who abandons checkout produces no terminal event — the order simply never progresses. Apply your own timeout when waiting on an order.

Track the order

Orders move through a normalized lifecycle:

Status	Meaning	Terminal
`pending`	Order created; awaiting payment or KYC	no
`processing`	Payment captured; crypto not yet sent	no
`completed`	Crypto sent on-chain	yes
`failed`	Order cancelled or declined	yes

Each transition fires an onramp-order webhook carrying the normalized status, Swapped’s rawStatus, the fiat receipt, and — once completed — the on-chain transactionId. You can also poll the account’s latest order:

const response = await fetch(
    `${DEPOSIT_SERVICE_URL}/onramp/swapped/status/0xUSER_ACCOUNT_ADDRESS`,
    { headers: { "x-api-key": API_KEY } },
);
const order = await response.json();
// {
//     ok: true,
//     orderId: "…",
//     status: "order_broadcasted",
//     orderCrypto: "USDC",
//     orderCryptoAmount: "98.61",
//     transactionId: "0xdef456…",
//     paidAmountUsd: 101.75,
//     onrampFeeUsd: 1.75,
//     paymentMethod: "creditcard",
//     receivedAt: "2025-01-15T12:03:00.000Z"
// }

Polling reflects the account’s most recent order and returns { ok: false, reason: "no_order" } before the first order update arrives. Full schema: GET /onramp/swapped/status/{smartAccount}. Once the order completes, the on-ramp hands off to the regular pipeline: transactionId reappears as the transactionHash on the deposit-received event, followed by the usual bridge events. Card and Apple Pay orders typically complete within minutes; bank transfers can take days. Orders stay trackable for 7 days.

Good to know

Session coverage — on-ramp purchases land on Base, so the account’s session set must include Base. The default registration flow covers every supported chain; if you restrict sessionChainIds, include Base or landed funds can’t be bridged.
Deposit whitelist — if you restrict accepted deposits, allow USDC on Base above your minimum. Otherwise every on-ramp purchase is rejected with deposit-rejected.
Same-chain target — when the account’s target is USDC on Base paid to the account itself, the purchase is already at its destination: no bridge events fire, and onramp-order with status: "completed" is your terminal signal.
KYC and limits — identity verification and purchase limits are handled by Swapped inside the widget.

​How it works

​Prerequisites

​Mint a checkout URL

​Fund from an exchange

​Show the widget

​Track the order

​Good to know

How it works

Prerequisites

Mint a checkout URL

Fund from an exchange

Show the widget

Track the order

Good to know