---
title: "Mint a signed Swapped widget URL (fiat on-ramp)"
method: POST
path: "/onramp/swapped/widget-url"
tags: ["Onramp"]
---

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

`POST /onramp/swapped/widget-url`

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.

## Headers

- `x-api-key` string — API key for authentication (omit when sending Authorization)
- `authorization` string — Bearer platform token (e.g. forwarded by user-service). Takes precedence over `x-api-key` when both are present.
- `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.
- `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.

## Request body

- SwappedWidgetUrlRequestBody
  - `smartAccount` string, required — Ethereum address (0x followed by 40 hex characters)
  - `email` string
  - `baseCountry` string — ISO-3166-1 alpha-2 country code
  - `baseCurrencyCode` string — ISO fiat currency code
  - `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.
  - `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.

## Response `200`

Signed widget URL

- SwappedUrlResponse
  - `ok` true, required
  - `url` string, required
  - `currencyCode` string, required
  - `sandbox` boolean, required
  - `externalCustomerId` string, required
  - `expiresAt` string, required
  - `exchangeFeeBps` integer

## Other responses

- `400` — Invalid request
- `401` — Authentication required or invalid credential
- `403` — API key lacks the required deposits scope, or the account is not registered to the calling project
- `500` — Server misconfigured or signing failed
- `503` — Swapped on-ramp is not configured

---

[API](https://skmtc.net/rhinestonewtf/apis/deposit-service-api.md) · [All operations](https://skmtc.net/rhinestonewtf/apis/deposit-service-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/rhinestonewtf/deposit-service-api/versions/ce4e0abfe33a/schema)