Sign in

v18

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-013469188.5 KB
Onramp

Mint a signed Swapped widget URL (fiat on-ramp)

Returns a signed Swapped widget URL the modal embeds in an iframe for the fiat on-ramp. The destination asset is fixed server-side (the configured currency code); the caller supplies the smart account that receives the crypto. methodSelectionSource: "personalized" opts a trusted regional selection into strict merchant-catalog validation; fallback, configured, and legacy selections retain exact-method pass-through.

post/onramp/swapped/widget-url

Headers

x-api-keystring

API key for authentication (omit when sending Authorization)

Example:your-api-key

API key for authentication (omit when sending Authorization)

authorizationstring

Bearer platform token (e.g. forwarded by user-service). Takes precedence over x-api-key when both are present.

Example:Bearer eyJhbGciOi...

Bearer platform token (e.g. forwarded by user-service). Takes precedence over x-api-key when both are present.

x-user-countrystring

Trusted edge-resolved ISO country. When present it overrides body.baseCountry and x-client-ip, and enables country-specific payment-method validation.

Example:PH

Trusted edge-resolved ISO country. When present it overrides body.baseCountry and x-client-ip, and enables country-specific payment-method validation.

x-client-ipstring

The end user's IP address as observed by the edge, for edges that can name the IP but cannot resolve a country themselves (no local GeoIP database). Used only when x-user-country is absent, and ignored unless it is a publicly-routable address. Prefer x-user-country when your edge already has a country — for example Cloudflare's cf-ipcountry — since it needs no lookup here.

Example:203.0.113.7

The end user's IP address as observed by the edge, for edges that can name the IP but cannot resolve a country themselves (no local GeoIP database). Used only when x-user-country is absent, and ignored unless it is a publicly-routable address. Prefer x-user-country when your edge already has a country — for example Cloudflare's cf-ipcountry — since it needs no lookup here.

Request body

smartAccountstring required

Ethereum address (0x followed by 40 hex characters)

emailstring
baseCountrystring

ISO-3166-1 alpha-2 country code

baseCurrencyCodestring

ISO fiat currency code

baseCurrencyAmountnumber
localestring
methodstring

Optional. Preselects a Swapped payment method (a payment_group) in the widget — e.g. "creditcard", "apple-pay", "bank-transfer", "skrill", "pix", "sepa-bank-transfer". Any Swapped-supported value is accepted and forwarded as-is; omit it to let Swapped auto-select the best method for the user based on their location and other signals. See Swapped's Get Payment Methods endpoint for the full, per-region list.

methodSelectionSource'personalized' | 'fallback' | 'configured'

How the caller obtained method. Use personalized only for a method rendered from the regional payment-method response; with a trusted x-user-country, this opts into strict catalog validation. fallback, configured, and omission preserve the legacy exact-method pass-through behavior.

Example request

{
  "smartAccount": "0x742d35Cc6634C0532925a3b844Bc9e7595f5bE91",
  "baseCountry": "US",
  "baseCurrencyCode": "USD",
  "method": "apple-pay",
  "methodSelectionSource": "personalized"
}

Response

Signed widget URL

oktrue required
urlstring required
currencyCodestring required
sandboxboolean required
externalCustomerIdstring required
expiresAtstring required
exchangeFeeBpsinteger