Developer reference

Provably — Developer reference

Provably mints a one-time, x402-gated bearer for every human verification. These pages document the verification API, the partner embed endpoint, and the on-chain payment flow that gates a /api/verify settlement. Read the prose, copy the curl snippet, then fire it from the embedded sandbox panel — same-origin, no external tools required.

Endpoints

/api/verify
Read / write verification state for a transaction id.
/api/badge/[humanId]
Render the verified-by trustmark as inline SVG.
x402 / payment flow
Authorize a /verify settlement with a USDC x402 proof.

How to read these pages

Each endpoint page renders three blocks in order: (1) the canonical request shape (method, path, headers, body schema), (2) the canonical response shape (status code, body schema — including the 402 envelope), and (3) a copy-curling example. The sandbox form on every page is wired to a same-origin proxy at /api/docs/<endpoint> so a partner can fire an actual call against the live DB without leaving the page.

No external account needed

The docs surface is public and unauthenticated. The x402 docs handler returns a SANDBOX-ONLY signed X-PAYMENT proof for the chosen transactionId so the partner can paste the literal header into their own client. Production /api/verify calls must mint their own settlement proof from a real facilitator; only the docs handler mints the sandbox example, and only when DOCS_SANDBOX_PROOF_KEY is injected.

Same-origin only

The docs surface runs against the same origin as /api — no NEXT_PUBLIC_API_URL is set, so the connect-src CSP stays at "self". All examples here resolve on the same host the visitor is currently browsing; the sandbox panel is a thin client island that fires the curl-shaped request via the typed apiFetch helper.