Skip to main content
POST
/
widget
/
session
POST /widget/session
curl --request POST \
  --url https://domain/widget/session \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: <content-type>' \
  --data '
{
  "partner_user_id": "<string>",
  "user_email": "<string>",
  "network": "<string>",
  "currency": "<string>",
  "amount": "<string>",
  "type": "<string>",
  "redirect_url": "<string>",
  "client_ip": "<string>",
  "address": "<string>"
}
'
{
  "merchant_transaction_id": "<string>",
  "widget_id": "<string>",
  "address": "<string>",
  "signature": "<string>",
  "init_token": "<string>",
  "init_token_type": "<string>",
  "currency": "<string>",
  "currencies": [
    "<string>"
  ],
  "fix_currency": true,
  "network": "<string>",
  "networks": [
    "<string>"
  ],
  "fix_network": [
    "<string>"
  ],
  "amount": "<string>",
  "fix_amount": true,
  "fiat_currency": "<string>",
  "fiat_currencies": [
    "<string>"
  ],
  "fix_fiat_currency": true,
  "fix_fiat_amount": true,
  "type": "<string>",
  "lang": "<string>",
  "theme": "<string>",
  "redirect_url": "<string>"
}

Documentation Index

Fetch the complete documentation index at: https://docs.proof.community/llms.txt

Use this file to discover all available pages before exploring further.

Creates a session for one widget transaction and returns every parameter the widget needs. This endpoint must be called from your backend server, not from the browser. Your server adds the client_token, reads the user’s real IP from the incoming request, and forwards it as client_ip. The response parameters are then passed to the frontend to launch the widget. The response is shaped to be passed directly to proofWidget.run({...}). Do not modify the returned values; pass them through verbatim.

​
Request

​
Headers

​
Authorization
string
required
Bearer token. Format: Bearer <client_token>.
​
Content-Type
string
required
application/json
​
Origin
string
The request Origin header must match one of your registered origins, or it is rejected with 403 forbidden. See Onboarding → Authentication.

​
Body

​
partner_user_id
string
required
Your stable internal user identifier. Used for KYC mapping and transaction attribution.
​
user_email
string
required
User’s email. Used to find or create the user identity.
​
network
string
required
Blockchain network for the crypto leg. Examples: TRC20, ERC20, BEP20.
​
currency
string
required
Crypto currency. Must be one of the currencies enabled for your integration. Proof confirms the list with you at onboarding.
​
amount
string
required
Crypto amount as a decimal string (e.g. "100", "99.50").
​
type
string
"buy" or "sell". Overrides the partner default from widget_config.type. Off-ramp (sell) must be enabled for your integration.
​
redirect_url
string
Overrides the partner default redirect_url for this session only.
​
client_ip
string
The end user’s real IP address, as seen by your backend from the incoming request (X-Forwarded-For or the connection’s remote address). Mixed into the session signature. Recommended — omitting it degrades fraud-signal quality.
​
address
string
Destination wallet address. Send this only if Proof told you to during onboarding. Otherwise omit it — Proof resolves the address for you and any value you send is ignored.

​
Response

​
merchant_transaction_id
string
Stable identifier for this session. Save it — every status surface keys off it.
​
widget_id
string
Your widget identifier. Pass as widgetId to the widget.
​
address
string
Resolved destination address. Pass as address to the widget verbatim.
​
signature
string
Cryptographic signature, format v2:<128-hex-chars>. Computed by Proof. Pass as signature to the widget verbatim.
​
init_token
string
Single-use session token. Single-use, expires after first use or one hour. Pass as initToken to the widget.
​
init_token_type
string
Pass as initTokenType to the widget.
​
currency
string
Crypto currency. Echo of the request.
​
currencies
string[]
Currencies offered in the widget’s currency selector. From widget_config.currencies.
​
fix_currency
boolean
Always true. The currency is locked at the value you requested.
​
network
string
Network. Echo of the request.
​
networks
string[]
Networks offered in the widget’s network selector. From widget_config.networks.
​
fix_network
string[]
Always [network] — the network is locked at the value you requested.
​
amount
string
Crypto amount. Echo of the request.
​
fix_amount
boolean
Always true. The amount is locked at the value you requested.
​
fiat_currency
string
Default fiat currency, from widget_config.fiat_currency.
​
fiat_currencies
string[]
Fiat currencies offered, from widget_config.fiat_currencies.
​
fix_fiat_currency
boolean
Always false. The user can change the fiat currency inside the widget.
​
fix_fiat_amount
boolean
Always true.
​
type
string
buy or sell. Resolved from the request body or widget_config.type.
​
lang
string
Widget language, from widget_config.lang.
​
theme
string
Widget theme, from widget_config.theme.
​
redirect_url
string
Redirect URL after the transaction completes. Resolved from the request or widget_config.redirect_url.

​
Examples

# Called from your backend server
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",
    "network": "TRC20",
    "currency": "USDT",
    "amount": "100",
    "type": "buy",
    "client_ip": "203.0.113.42"
  }'
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_partner_authorization",
  "currency": "USDT",
  "currencies": ["USDT"],
  "fix_currency": true,
  "network": "TRC20",
  "networks": ["TRC20", "ERC20"],
  "fix_network": ["TRC20"],
  "amount": "100",
  "fix_amount": true,
  "fiat_currency": "EUR",
  "fiat_currencies": ["EUR", "USD"],
  "fix_fiat_currency": false,
  "fix_fiat_amount": true,
  "type": "buy",
  "lang": "en",
  "theme": "light",
  "redirect_url": "https://app.example.com/done"
}

​
Errors

See Error Handling. The most common session-creation errors:
HTTPerrorcodeCause
400invalid_requestvalidation_errorA required field is missing or has the wrong type
400invalid_requestcurrency_not_allowedcurrency is not enabled for your integration
400wallet_not_supportedWALLET_NOT_SUPPORTEDNo active wallet for the requested currency + network — contact Proof to provision one
401unauthorisedinvalid_tokenclient_token is missing or inactive
403forbiddenforbidden_originThe request Origin is not on your allowlist
502upstream_errorprovider_errorAn external service returned an error; retry with the same body