Reference
HTTP API
Endpoints, authentication and operation states.
All endpoints are under the site's origin and exchange JSON. Errors answer { "error": { "code", "message", "requestId" } }.
Public#
| Method and path | Returns |
|---|
GET /api/config | Program, public RPC URL, genesis hash, proof artifact manifest and its pinned digest, region and status names |
GET /api/network | Governance config, verifiers, the circuit, the upgrade authority, the pass fee and the pass fees the protocol holds, and chain time |
GET /api/rules | Every rule set with its name, and the index position |
GET /api/health/live | { "status": "ok" } while the server runs |
GET /api/health/ready | waiting while the program, governance, circuit or pass fee is not set up; ok once ready; 503 when the database, the chain or the index fails, or jobs failed |
POST /api/verifier/webhook | Provider callbacks, authenticated by HMAC |
Sign-in#
| Method and path | Body | Returns |
|---|
POST /api/auth/challenge | wallet | challengeId, message, expiresAt |
POST /api/auth/verify | challengeId, wallet, signature | Sets the session cookie |
GET /api/auth/session | — | The signed-in wallet, or null |
POST /api/auth/logout | — | Ends the session |
Signed in#
| Method and path | Body | Returns |
|---|
GET /api/passport | — | Credential, passes, rule sets with live-pass counts, bindings, index |
POST /api/verification-sessions | returnUrl | The verifier's hosted URL |
POST /api/proofs/context | rule | Credential, rule set, verifier, circuit, the pass fee, chain time |
POST /api/rules | name, nonce, clauses, maxPassAgeSeconds | An operation with its unsigned transaction and the rule set's address |
POST /api/mint-bindings | mint, rule, requireSource | An operation |
POST /api/proofs | rule, expiresAt, proof | An operation |
POST /api/mints/issue | mint, destination, amount | An operation |
POST /api/transfers | mint, source, destination, amount | An operation |
POST /api/transactions/submit | operationId, transaction | The operation, now queued |
GET /api/operations/{id} | — | The operation's state |
Every POST must carry the site's Origin. Preparing endpoints need an Idempotency-Key.
Operation states#
| State | Meaning |
|---|
DRAFT | Prepared, not signed |
EXPIRED | Never signed within 90 seconds |
QUEUED | Signed and saved |
SUBMITTED | Broadcast; waiting for finality |
UNRESOLVED | The RPC could not yet establish the outcome; Writ keeps checking the same signature |
FINALIZED | Executed and final |
FAILED | Final, with an on-chain error; nothing changed |
Error codes#
| Code | Status | Meaning |
|---|
AUTHENTICATION_REQUIRED, SESSION_EXPIRED | 401 | Sign in again |
ORIGIN_MISMATCH | 403 | The request came from another origin |
IDEMPOTENCY_KEY_REQUIRED | 400 | Missing or malformed key |
IDEMPOTENCY_CONFLICT | 409 | The key was used for a different body |
SIGNED_OPERATION_PENDING | 409 | Another signed operation has no final result yet |
TRANSACTION_MISMATCH | 400 | The signed bytes differ from the prepared message |
DRAFT_EXPIRED | 409 | Prepare again |
INDEX_STALE | 503 | The index is catching up; retry shortly |
PROTOCOL_PAUSED | 503 | Writ is paused |
CREDENTIAL_REQUIRED, CREDENTIAL_EXPIRED, VERIFIER_INACTIVE | 409 | The credential cannot prove |
PASS_FEE_UNFUNDED | 409 | The rule set's pass funds cannot cover the pass fee |
PASS_FEE_UNSET | 503 | Governance has not set the pass fee yet |
MINT_NOT_BINDABLE, UNSUPPORTED_MINT_EXTENSIONS | 409, 400 | The mint does not meet the binding profile |
TOKEN_ACCOUNT_NOT_FOUND | 409 | A token account does not exist at finalized commitment yet |
RATE_LIMITED | 429 | Too many requests |