Skip to main content
POST
/
v0
/
ramp
/
sessions
Open a ramp widget session
curl --request POST \
  --url https://api.sumvin.com/v0/ramp/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-juno-jwt: <api-key>' \
  --data '
{
  "source_amount": "100",
  "from_asset": "<string>",
  "to_asset": "<string>",
  "wallet_address": "<string>",
  "country_code": "US",
  "service_provider": "<string>",
  "idempotency_key": "partner-retry-2026-05-07-12345"
}
'
{
  "_links": {},
  "session": {
    "id": "<string>",
    "widget_url": "<string>",
    "token": "<string>",
    "service_provider_widget_url": "<string>",
    "external_session_id": "<string>"
  }
}

Authorizations

​
x-juno-jwt
string
header
required

JWT issued by Dynamic Labs or Privy. Sent in the x-juno-jwt header on every authenticated request.

Headers

​
x-juno-orgid
string | null

Tenant org ID for multi-tenant auth

​
x-juno-jwt
string | null
​
x-sumvin-token
string | null
​
x-sumvin-pat
string | null
​
x-sumvin-pint-token
string | null
​
X-Timestamp-Format
string

Controls how timestamp fields are serialized in JSON response bodies.

Default (header omitted or any other value): epoch milliseconds as integers. iso8601: UTC ISO 8601 strings of the form YYYY-MM-DDTHH:MM:SSZ.

Example: with X-Timestamp-Format: iso8601, the field value 1704067200000 becomes "2024-01-01T00:00:00Z".

Affected fields (recursively, in dicts and arrays): any field whose name ends in _at, plus the literal field names timestamp, period_start, and period_end. All other fields are passed through unchanged.

Only iso8601 is recognized. Any other value (or omitting the header) yields the default epoch-ms representation; the server does not reject unknown values, so this is documented as an example rather than an enum to keep generated clients permissive.

Example:

"iso8601"

Body

application/json

Inputs for opening a hosted ramp widget session.

Direction (buy or sell) is inferred from which side is fiat. chain_id always describes the crypto leg.

​
source_amount
required

Amount of from_asset the user is selling. Must be greater than zero.

Required range: x > 0
Example:

"100"

​
from_asset
string
required

Asset.symbol value the user is paying with. Fiat ISO 4217 (e.g. USD, EUR) for buys, or a crypto symbol (e.g. USDC, ETH) for sells. See Supported values.

Minimum string length: 1
Examples:

"USD"

"EUR"

"USDC"

​
to_asset
string
required

Asset.symbol value the user is receiving. Crypto symbol for buys, fiat ISO 4217 for sells.

Minimum string length: 1
Examples:

"USDC"

"ETH"

"USD"

​
chain_id
enum<integer>
required

EIP-155 chain id of the crypto leg.

Available options:
1,
10,
137,
42161,
8453,
43114,
56,
1328,
1329
Examples:

1

137

8453

​
wallet_address
string
required

Destination wallet address for the crypto leg of the transaction.

Minimum string length: 1
​
country_code
enum<string>
default:US

User's country (ISO 3166-1 alpha-2). Filters quotes to providers live in that market.

Available options:
US,
CA,
MX,
BR,
AR,
CL,
CO,
PE,
GB,
DE,
FR,
IT,
ES,
NL,
BE,
IE,
PT,
AT,
CH,
SE,
NO,
DK,
FI,
PL,
CZ,
GR,
SG,
HK,
JP,
KR,
AU,
NZ,
IN,
TH,
PH,
MY,
ID,
AE,
SA,
IL,
TR,
ZA,
NG
​
payment_method_type
enum<string> | null

Restrict the session to one rail. Omit to let the provider pick. See Supported values.

Available options:
CARD,
CREDIT_DEBIT_CARD,
VISA,
MASTERCARD,
ACH,
SEPA,
BACS,
BANK_TRANSFER,
LOCAL_BANK_TRANSFER,
LOCAL,
PIX,
MOBILE_WALLET,
APPLE_PAY,
GOOGLE_PAY,
SAMSUNG_PAY
​
service_provider
string | null

Pin the session to a specific service provider (e.g. TRANSAK, STRIPE). Omit to let the provider router decide.

​
idempotency_key
string | null

Caller-supplied key making this request safe to retry. When supplied, the same key submitted within 24 hours returns the original session (HTTP 208 Already Reported) without opening a new widget. Keys are scoped to the caller's x-juno-orgid and the authenticated user, so neither partners nor end-users within a single tenant can collide with each other. When omitted, every call mints a fresh session.

Maximum string length: 128
Example:

"partner-retry-2026-05-07-12345"

Response

Successful Response

​
_links
Links · object
required

HAL-style hypermedia links for navigation and available actions.

​
session
SessionData · object
required

A hosted ramp widget session.

Render widget_url in a webview or iframe to let the user complete the trade. The session is single-use and tied to the authenticated user's Meld customer record.