---
title: "Start an onramp order"
method: POST
path: "/onramp/orders"
tags: ["Onramp"]
---

# Start an onramp order

`POST /onramp/orders`

## Request

- Base URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor`
- URL: `https://v1.orchestrator.rhinestone.dev/deposit-processor/onramp/orders`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/docs/onramp/orders/post.ts> (a function with typed inputs; its response is checked against the schema)

Signs a hosted checkout for the account. The order is visible at `GET /onramp/orders/{orderId}` once the provider first reports it.

## Headers

- `x-api-key` string: API key for authentication
- `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

- union
  - SwappedFiatOrderRequest
    - `provider` 'swapped', required
    - `account` string, required: The registered account to fund
    - `kind` 'fiat', required
    - `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", "google-pay". 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.
  - SwappedExchangeOrderRequest
    - `provider` 'swapped', required
    - `account` string, required: The registered account to fund
    - `kind` 'exchange', required
    - `baseCountry` string: ISO-3166-1 alpha-2 country code
    - `baseCurrencyCode` string: ISO fiat currency code
    - `locale` string
    - `connection` string
    - `connections` string[]
    - `merchantName` string: Optional. Overrides the merchant name Swapped Connect shows on its confirm screen — both the "To:" row and its tooltip ("Funds will be delivered to your <name> wallet."). Omit it to inherit the Rhinestone default. Send it raw; the service URL-encodes it.
    - `merchantLogoUrl` string, uri: Optional. Publicly accessible HTTPS URL of the merchant's logo, shown beside `merchantName` on the Swapped Connect confirm screen. PNG or SVG recommended. Send it raw; the service URL-encodes it.

## Response `202`

Hosted checkout ready

- OnrampOrderStarted
  - `orderId` string, uuid, required
  - `nextAction` HostedNextAction, required
    - `type` 'hosted', required
    - `url` string, required
    - `presentation` 'iframe', required
  - `expiresAt` string, date-time, required: Start the checkout before this

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key or bearer
- `403`: API key lacks deposits:read, or the account is not yours
- `500`: Internal failure serving the request
- `503`: Onramp not configured, or a dependency is unavailable

## Changes

- **2026-11-06** `aa1767d704fa`: 1 breaking, 20 warning, 8 info
  - the `nextAction/url` response's property format changed from `uri` to no format for status `202`
  - added the new `PROVIDER_FORBIDDEN` enum value to the `code` response property for the response status `400`
  - added the new `PROVIDER_FORBIDDEN` enum value to the `code` response property for the response status `401`
  - added the new `PROVIDER_FORBIDDEN` enum value to the `code` response property for the response status `403`
  - …25 more
- **2026-10-07** `8b74181ef9e2`: 5 info
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `401` status
  - added the optional property `code` to the response with the `403` status
  - added the optional property `code` to the response with the `500` status
  - …1 more
- **2026-09-30** `a6fd693c3d5f`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/changes/onramp/orders/post.md)

---

[API](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api.md) - [All operations](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/llms.txt) - [OpenAPI document](https://skmtc.dev/rhinestonewtf/apis/deposit-service-api/revisions/aa1767d704fa?raw)