Quickstart

Prerequisites

You have completed onboarding and received a client_token and widget_id.
You have a backend server whose IP is registered with Proof.
You have a partner_user_id (your internal, stable user identifier) and the user’s email.
You know which network and currency the user wants to transact in (e.g. TRC20 + USDT).

Step 1 — Request a session from your backend

Your frontend calls your own backend. Your backend calls POST /widget/session with the client_token (kept server-side) and the user’s real IP in client_ip.

# Your backend → Proof API
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",
  "network": "TRC20",
  "amount": "100",
  "fix_currency": true,
  "fix_network": ["TRC20"],
  "fix_amount": true,
  "fiat_currency": "EUR",
  "type": "buy"
}

Save merchant_transaction_id — you use it everywhere downstream (polling, WebSocket, webhook).

Your backend returns the session parameters to the frontend (minus the client_token, which never leaves your server). For the full request and response field reference, see POST /widget/session.

Your frontend receives the session parameters from your backend and passes them directly to proofWidget.run(). No client_token is needed on the frontend.

<div id="proof-widget"></div>

<script src="https://widget.proof.community/widget.2.0.js"></script>
<script>
  // `session` comes from your own backend endpoint, not from Proof directly
  proofWidget.run({
    widgetId:              session.widget_id,
    host:                  document.getElementById("proof-widget"),
    address:               session.address,
    signature:             session.signature,
    initToken:             session.init_token,
    initTokenType:         session.init_token_type,
    merchantTransactionId: session.merchant_transaction_id,
    currency:              session.currency,
    network:               session.network,
    amount:                session.amount,
    fixCurrency:           session.fix_currency,
    fixNetwork:            session.fix_network,
    fixAmount:             session.fix_amount,
    fiatCurrency:          session.fiat_currency,
    type:                  session.type,
    onStatusChange: function(data) {
      console.log("Widget status:", data.status);
    }
  });
</script>

The widget renders inside #proof-widget. The user completes identity verification (first time) and payment inside the widget.

Step 3 — Track transaction status

All status calls use your client_token and must go through your backend. Pick one of three delivery channels:

Polling (from your backend)

# Your backend → Proof API
curl https://DOMAIN/widget/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer <client_token>"

Poll every 5–10 seconds while status is pending or processing. Stop on completed, failed, or cancelled. See GET /widget/transactions/{id}.

WebSocket (from your backend)

// Node.js — server-side subscription
const WebSocket = require("ws");
const ws = new WebSocket(
  "wss://DOMAIN/ws?tx_id=550e8400-e29b-41d4-a716-446655440000",
  { headers: { Authorization: "Bearer <client_token>" } }
);
ws.on("message", (data) => {
  const msg = JSON.parse(data);
  if (msg.event === "tx.update") console.log(msg.status);
});

One connection subscribes to one merchant_transaction_id. See WebSocket for details and reconnection patterns.

Outbound webhook

If you provided a webhook_url at onboarding, Proof POSTs the normalized transaction event to that URL on every status change. See Partner Webhook.

Full example

// POST /your-api/widget-session
// Called by your frontend; client_token never leaves this file
async function createWidgetSession(req, res) {
  const userIp =
    req.headers["x-forwarded-for"]?.split(",")[0].trim() ||
    req.socket.remoteAddress;

  const session = await fetch("https://DOMAIN/widget/session", {
    method: "POST",
    headers: {
      "Authorization": "Bearer <client_token>",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      partner_user_id: req.body.userId,
      user_email:      req.body.userEmail,
      network:         "TRC20",
      currency:        "USDT",
      amount:          "100",
      type:            "buy",
      client_ip:       userIp
    })
  }).then(r => r.json());

  // Return session params — client_token is not included
  res.json(session);
}

// 1. Ask your backend for session params
const session = await fetch("/your-api/widget-session", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ userId: "user-123", userEmail: "user@example.com" })
}).then(r => r.json());

// 2. Launch widget
proofWidget.run({
  widgetId:              session.widget_id,
  host:                  document.getElementById("proof-widget"),
  address:               session.address,
  signature:             session.signature,
  initToken:             session.init_token,
  initTokenType:         session.init_token_type,
  merchantTransactionId: session.merchant_transaction_id,
  currency:              session.currency,
  network:               session.network,
  amount:                session.amount,
  fixCurrency:           session.fix_currency,
  fixNetwork:            session.fix_network,
  fixAmount:             session.fix_amount,
  fiatCurrency:          session.fiat_currency,
  type:                  session.type,
  onStatusChange:        (data) => console.log(data.status)
});

Next steps

Transaction Status

Polling, WebSocket, and webhook delivery in detail.

Off-Ramp (Sell)

Enable sell flow for your users.

Mobile

iOS and Android setup for camera and payments.

Error Handling

Real error codes and how to handle them.

Getting started

Guides

API Reference

Prerequisites

Step 1 — Request a session from your backend

Step 2 — Embed the widget

Step 3 — Track transaction status

Polling (from your backend)

WebSocket (from your backend)

Outbound webhook

Full example

Next steps

Transaction Status

Off-Ramp (Sell)

Mobile

Error Handling

​Prerequisites

​Step 1 — Request a session from your backend

​Step 2 — Embed the widget

​Step 3 — Track transaction status

​Polling (from your backend)

​WebSocket (from your backend)

​Outbound webhook

​Full example

​Next steps

Transaction Status

Off-Ramp (Sell)

Mobile

Error Handling

Prerequisites

Step 1 — Request a session from your backend

Step 2 — Embed the widget

Step 3 — Track transaction status

Polling (from your backend)

WebSocket (from your backend)

Outbound webhook

Full example

Next steps