HTTP API reference
Gateway and facilitator routes, authentication, result fields, and status semantics.
Origins and authentication
The local gateway defaults to http://127.0.0.1:3000 and the local facilitator to http://127.0.0.1:3002. The documented public gateway origin is https://sovrx402.54-199-0-131.sslip.io. Select HTTPS before sending credentials; SDK requests reject redirects.
Production gateway routes /alpha, /status, /resources, and /results require Authorization: Bearer with GATEWAY_API_TOKEN. Resource signatures and payment signatures do not replace this service credential. Gateway /health does not require it. Local Bearer protection applies when configured.
Protected routes return 401 UNAUTHORIZED before route validation when the Bearer credential is missing or invalid. Rate limiting can return 429 RATE_LIMITED with Retry-After. Tokens are provisioned privately; there is no public token-issuance endpoint documented here.
Gateway routes
| Method and route | Inputs | Behavior |
|---|---|---|
| GET /health | No agent or credential required. | 200 ok, or 503 maintenance/recovery-required. Reports service controls and network/contract identifiers. |
| GET /status?agent=<address> | Gateway Bearer when enabled; valid agent address. | 200 with agent, score, debt, limit, pricePerCall, chainId, network, payTo, and payTokenAddress. Invalid agent: 400; RPC/internal error: 500. |
| GET /alpha?agent=<address> | Gateway Bearer when enabled. Legacy credit proof or x402 payment; resource auth selects the new path. | Fixed example data. Legacy path: 403 unregistered, 402 payment required/rejected, 401 invalid credit proof, 502 paid but score failed, or 503 maintenance. |
| GET /resources/:name | Gateway Bearer when enabled plus X-SOVRx402-Request-Auth; x402 signature when prepaid. | Deployed API: authenticated named resource invocation, billed once per stored request identity. |
| GET /results/:id | Gateway Bearer when enabled plus original payer's result-purpose resource signature. | Deployed API: retrieve a charged result or its pending/unpaid state; unknown or other-payer result returns 404. |
Default resources
address-snapshot reads nativeBalance and tokenBalance for balances; registered, score, creditLimit, and debt for credit. The all view includes both sets. Token amounts and score are decimal strings. Reads are pinned to one block and its hash is checked again before preparation succeeds.
There is no address query for choosing an arbitrary account in this handler: the target is the authenticated payer. Unknown query keys or an invalid view fail resource preparation. Duplicate query keys are rejected by resource authentication. These signed, billed snapshots are separate from the website's public-address explorer reads.
| Name | Business query | Result data |
|---|---|---|
| alpha | None. An optional agent must match the signer. | The fixed string Alpha data: AI credit system working! |
| address-snapshot | view=all (default), view=balances, or view=credit. | Authenticated payer address, chainId, blockNumber, blockHash, timestamp, and selected balances/credit fields. |
Signature headers
Use the SDK's exported buildResourceAuthHeader and canonicalResourceQuery helpers when constructing resource requests manually. The resource domain is SOVRx402Resource, version 1, with the actual chain ID and Registry proxy as verifyingContract. Reuse a request ID with a fresh signature for recovery; do not invent a payment ID or hand-roll query hashing.
| Header | Purpose |
|---|---|
| X-SOVRx402-Request-Auth | JSON EIP-712 ResourceAuth payload for invoke/result. Binds the request and Registry domain; SDK creates it. |
| X-SOVRx402-Credit-Auth | Legacy /alpha credit authorization with a durable consumed nonce. X-SOVRx402-Signature is a compatibility alias. |
| PAYMENT-REQUIRED | x402 payment requirements returned with a payment challenge. |
| PAYMENT-SIGNATURE | x402 payment authorization supplied on the prepaid retry. |
| X-SOVRx402-Request-Id | Server response identifier for the new resource/result flow. |
Resource response contract
| Status | Meaning |
|---|---|
| 200 | Confirmed billing and stored data: requestId, data, resultHash, charged, mode, payer, transaction; prepaid can also include paymentId and creditRecorded. |
| 202 BILLING_PENDING | Billing is unresolved; no completed result is returned. Preserve the request ID. |
| 401 AUTH_REQUIRED / AUTH_INVALID / AUTH_EXPIRED | Missing, invalid, or expired resource signature; reason identifies the failed check. |
| 402 | x402 challenge or payment-processing rejection before a charged result. |
| 403 NOT_REGISTERED | Agent must register before a new invocation. |
| 404 RESOURCE_NOT_FOUND / RESULT_NOT_FOUND | Unknown resource, unknown request, or a result belonging to another payer. |
| 409 | REQUEST_CONFLICT, CREDIT_EXHAUSTED, PAYMENT_BINDING_MISMATCH, NOT_CHARGED, or BILLING_FAILED; inspect code before deciding how to proceed. |
| 502 RESOURCE_FAILED | Resource preparation failed before billing; charged is 0. |
| 503 | Payment pause, required credit recovery, blocked result storage, or resource/result service failure. |
Facilitator routes
These belong to the separate facilitator, which is not exposed by the documented public gateway ingress. /verify, /settle, and /supported use FACILITATOR_API_TOKEN when configured; it must differ from the gateway token.
| Method and route | Behavior |
|---|---|
| GET /health | Public within the service network. 200 ok or 503 maintenance/reconciliation-required. |
| GET /supported | Returns the x402 supported-kind response; failures can return 500. |
| POST /verify | JSON body requires paymentPayload and paymentRequirements. 200 carries isValid; missing fields return 400. Does not settle payment. |
| POST /settle | Same required body fields. May broadcast settlement; inspect success and transaction in the 200 response. Maintenance returns 503; malformed input returns 400; exceptions can return 500. |