Skip to main content
POST
POST /widget/session
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

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

Body

string
required
Your stable internal user identifier. Used for KYC mapping and transaction attribution.
string
required
User’s email. Used to find or create the user identity.
string
required
Blockchain network for the crypto leg. Examples: TRC20, ERC20, BEP20.
string
required
Crypto currency. Must be one of the currencies enabled for your integration. Proof confirms the list with you at onboarding.
string
required
Crypto amount as a decimal string (e.g. "100", "99.50").
string
"buy" or "sell". Overrides the partner default from widget_config.type. Off-ramp (sell) must be enabled for your integration.
string
Overrides the partner default redirect_url for this session only.
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.
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

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

Examples

Response

Errors

See Error Handling. The most common session-creation errors: