Skip to main content
POST
Mint a signed Swapped widget URL (fiat on-ramp)

Headers

x-api-key
string

API key for authentication (omit when sending Authorization)

Example:

"your-api-key"

authorization
string

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

Example:

"Bearer eyJhbGciOi..."

x-user-country
string

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

Pattern: ^[A-Z]{2}$
Example:

"PH"

x-client-ip
string

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"

Body

application/json
smartAccount
string
required

Ethereum address (0x followed by 40 hex characters)

Pattern: ^0x[a-fA-F0-9]{40}$
Example:

"0x742d35Cc6634C0532925a3b844Bc9e7595f5bE91"

email
string
baseCountry
string

ISO-3166-1 alpha-2 country code

Pattern: ^[A-Z]{2}$
Example:

"US"

baseCurrencyCode
string

ISO fiat currency code

Pattern: ^[A-Z]{3,4}$
Example:

"USD"

baseCurrencyAmount
number
locale
string
method
string

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.

Example:

"apple-pay"

methodSelectionSource
enum<string>

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.

Available options:
personalized,
fallback,
configured
Example:

"personalized"

Response

Signed widget URL

ok
enum<boolean>
required
Available options:
true
url
string
required
currencyCode
string
required
sandbox
boolean
required
externalCustomerId
string
required
expiresAt
string
required
exchangeFeeBps
integer
Required range: x >= 0