Skip to main content
POST
/
widget
/
session
POST /widget/session
curl --request POST \
  --url https://domain/widget/session \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "partner_user_id": "<string>",
  "user_email": "<string>",
  "currency": "<string>",
  "network": "<string>",
  "fiat_currency": "<string>",
  "fiat_amount": "<string>",
  "crypto_amount": "<string>",
  "type": "<string>",
  "redirect_url": "<string>"
}
'
{
  "merchant_transaction_id": "<string>",
  "widget_id": "<string>",
  "address": "<string>",
  "signature": "<string>",
  "init_token": "<string>",
  "init_token_type": "<string>",
  "currency": "<string>",
  "fiat_currency": "<string>",
  "fiat_amount": "<string>",
  "type": "<string>",
  "widget_url": "<string>"
}

​
Request

​
Authorization
string
required
Bearer token. Format: Bearer <client_token>
​
partner_user_id
string
required
Your stable internal user identifier. Used for KYC tracking and transaction mapping.
​
user_email
string
required
User’s email address. Used to match or create the KYC profile.
​
currency
string
required
Crypto asset. Currently supported: USDT.
​
network
string
Blockchain network. Supported: TRC20 (default), ERC20.
​
fiat_currency
string
required
Fiat currency. Supported: EUR, USD.
​
fiat_amount
string
Pre-fills the amount field in the widget. If omitted, the user sets it manually. Do not send together with crypto_amount.
​
crypto_amount
string
Alternative to fiat_amount. Pre-fills the crypto amount. Do not send together with fiat_amount.
​
type
string
buy (default) or sell. Off-ramp (sell) must be enabled for your integration.
​
redirect_url
string
URL to redirect to after the transaction is completed or cancelled.

​
Response

​
merchant_transaction_id
string
Unique transaction identifier. Save this — it is used to track status and is stable across retries.
​
widget_id
string
Proof widget identifier for your integration.
​
address
string
Proof wallet address for the transaction. Pass this to the widget as-is.
​
signature
string
Cryptographic signature v2:.... Computed by Proof. Pass directly to the widget.
​
init_token
string
Single-use session token. Expires after first use or 1 hour.
​
init_token_type
string
Always sdk_customer_token.
​
currency
string
Crypto currency (echoed from request).
​
fiat_currency
string
Fiat currency (echoed from request).
​
fiat_amount
string
Fiat amount (echoed from request, if provided).
​
type
string
buy or sell (echoed from request).
​
widget_url
string
URL of the Proof widget embed script.

​
Examples

curl -X POST https://DOMAIN/widget/session \
  -H "Authorization: Bearer <client_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_user_id": "user-123",
    "user_email": "user@example.com",
    "currency": "USDT",
    "fiat_currency": "EUR",
    "fiat_amount": "100",
    "type": "buy"
  }'
Response
{
  "merchant_transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "widget_id": "fb359d09-fff6-4b1f-906c-b9062b135065",
  "address": "TRx1a2b3c4d5e6f...",
  "signature": "v2:a1b2c3d4e5f6...",
  "init_token": "eyJhbGciOi...",
  "init_token_type": "sdk_customer_token",
  "currency": "USDT",
  "fiat_currency": "EUR",
  "fiat_amount": "100",
  "type": "buy",
  "widget_url": "https://widget.proof.community/widget.2.0.js"
}