REST API
Complete HTTP endpoint, schema, authentication, SSE stream, and error envelope reference for the Tova Hono API.
Base URL and contract version
| Setting | Value |
|---|---|
| Default local API URL | http://127.0.0.1:37402 |
| Contract package | @tova/contract (0.1.0) |
| Allowed custom headers | X-Fixture, X-Fixture-Session, X-Tova-Settlement, Authorization, Last-Event-ID, solana-client |
| Exposed response headers | X-Tova-Quote, X-Tova-Receipt |
All build endpoints return an unsigned versioned (v0) Solana transaction in TxBuildResponse:
{
"id": "tx_a1b2c3d4e5f6",
"transactionBase64": "...",
"blockhash": "...",
"lastValidBlockHeight": 312500000,
"estimatedUnits": 38631,
"targetAddress": "...",
"settlementId": "1732270000000",
"proofSizeBytes": 192,
"expiresAt": "2026-11-22T10:54:20.000Z"
}All list endpoints accept limit and cursor pagination parameters and return { items, page: { nextCursor, hasMore }, asOf }.
Health, stats, streams, and RPC
| Method | Path | Description |
|---|---|---|
GET | /health | Returns { status, mode, cluster, programId, asOf } (status is ready, waiting, or fixture) |
GET | /v1/protocol/stats | Returns ProtocolStats including counters, feeBps, feeRecipient, token, and pdaLayout |
GET | /v1/events | Server-Sent Events (SSE) stream of indexed protocol events; supports Last-Event-ID |
POST | /rpc | Solana JSON-RPC relay (enabled in chain mode) |
Authentication (SIWS)
| Method | Path | Description |
|---|---|---|
GET | /auth/nonce | Issues a Sign-In With Solana nonce (statement: "Sign in to Tova Protocol") |
POST | /auth/verify | Verifies signed SIWS payload and returns session token (Authorization: Bearer <token>) |
GET | /auth/session | Returns active session state |
POST | /auth/logout | Invalidates active session |
Shielded Ring Vaults
| Method | Path | Query / Body | Response |
|---|---|---|---|
GET | /v1/vaults | Query: principal?, mint?, cursor?, limit? | VaultsPage |
GET | /v1/vaults/:vault | Path: vault PDA | VaultDetail (includes notes[]) |
POST | /v1/vaults/build | CreateVaultRequest (alias: POST /api/vaults/build) | TxBuildResponse |
POST | /v1/vaults/:vault/deposit/build | DepositShieldedRequest | TxBuildResponse |
POST | /v1/vaults/:vault/withdraw/build | WithdrawShieldedRequest | TxBuildResponse |
CreateVaultRequest
| Field | Type | Required |
|---|---|---|
principal | Solana Address | Yes |
mint | Solana Address | Yes |
viewingKeyTag | Hex32 (64 hex chars) | Yes |
auditorKeyTag | Hex32 | No |
initialDepositLamports | U64 decimal string | No |
initialCommitment | Hex32 | No |
initialCiphertext | string (max 4096 chars) | No |
DepositShieldedRequest
{ principal: Address, amountLamports: PositiveU64, commitment: Hex32, ciphertext?: string }
WithdrawShieldedRequest
{ principal: Address, amountLamports: PositiveU64, nullifierHash: Hex32, proofBase64?: Base64 }
Shielded Mandates
| Method | Path | Query / Body | Response |
|---|---|---|---|
GET | /v1/mandates | Query: vault?, principal?, agent?, status? (Active, Revoked, Expired) | MandatesPage |
GET | /v1/mandates/:mandate | Path: mandate PDA | MandateItem |
POST | /v1/mandates/build | IssueMandateRequest | TxBuildResponse |
POST | /v1/mandates/:mandate/revoke/build | { principal: Address } | TxBuildResponse |
IssueMandateRequest
| Field | Type | Required |
|---|---|---|
principal | Address | Yes |
vault | Address | Yes |
agent | Address | Yes |
mandateId | U64 decimal string | No |
perCallCapLamports | PositiveU64 | Yes |
epochBudgetLamports | PositiveU64 | Yes |
epochDurationSlots | integer (10..50000000) | Yes |
allowedProvider | Address | No |
expirySlot | positive integer | Yes |
auditorKeyTag | Hex32 | No |
Attested Providers
| Method | Path | Query / Body | Response |
|---|---|---|---|
GET | /v1/providers | Query: hardwareType? (IntelTDX, AmdSevSnp, LocalAttested) | ProvidersPage |
GET | /v1/providers/:provider | Path: provider PDA or providerPubkey | ProviderItem |
POST | /v1/providers/build | RegisterProviderRequest | TxBuildResponse |
POST | /v1/providers/:provider/attestation/build | UpdateProviderAttestationRequest | TxBuildResponse |
RegisterProviderRequest
{ providerPubkey: Address, name: string (2..64), endpointUrl: url (<=256), attestationPubkey: Address, hardwareType: "IntelTDX" | "AmdSevSnp" | "LocalAttested", attestationExpirySlot: int, stakeLamports: PositiveU64, pricePerCallLamports?: PositiveU64 }
UpdateProviderAttestationRequest
{ providerPubkey: Address, attestationPubkey: Address, hardwareType: "IntelTDX" | "AmdSevSnp" | "LocalAttested", attestationExpirySlot: int }
Atomic 402 Settlements
| Method | Path | Query / Body | Response |
|---|---|---|---|
GET | /v1/settlements | Query: vault?, mandate?, provider?, status? (Open, Claimed, Refunded) | SettlementsPage |
GET | /v1/settlements/:settlement | Path: settlement PDA or settlementId | SettlementItem |
POST | /v1/settlements/open/build | OpenSettlementRequest | TxBuildResponse |
POST | /v1/settlements/:settlement/claim/build | ClaimSettlementRequest | TxBuildResponse |
POST | /v1/settlements/:settlement/refund/build | { caller: Address } | TxBuildResponse |
OpenSettlementRequest
{ agent: Address, vault: Address, mandate: Address, provider: Address, settlementId?: U64, amountLamports: PositiveU64, requestHash: Hex32, deadlineSlot: int, amountCommitment?: Hex32, nullifierHash?: Hex32, proofBase64?: Base64, encryptedReceipt?: string }
ClaimSettlementRequest
{ providerPubkey: Address, responseHash: Hex32, attestationSignature: Hex64, slot: int, amountLamports: PositiveU64 }
Transactions
| Method | Path | Body / Params | Response |
|---|---|---|---|
POST | /v1/transactions/submit | { id: string, signedTransactionBase64?: Base64, signature?: Signature } | TxStatusResponse |
GET | /v1/transactions/:id | Path: build id | TxStatusResponse |
TxStatusResponse.status is one of built, submitted, confirmed, finalized, failed, or expired.
Attested HTTP 402 Demo Provider
POST /api/demo-provider/infer
Request body (DemoInferRequest):
{
"prompt": "Summarize shielded 402 receipt verification",
"model": "tova-tee-llama-3-8b",
"mandate": "<optionalMandatePda>"
}- Without `X-Tova-Settlement`: Returns
HTTP 402withX-Tova-Quoteheader and{ error: { code: "PAYMENT_REQUIRED", ... }, quote }. - With `X-Tova-Settlement: <settlementId>`: Verifies the
Opensettlement, signs a real Ed25519 TEE receipt, marks the settlementClaimed, and returnsHTTP 200withDemoInferSuccess(output,model,settlementId,settlementAddress,requestHash,responseHash,slot,attestationSignature,attestationPubkey,hardwareType,claimTxSignature,feeLamports,encryptedReceipt).
Error envelope and codes
Every failed response returns:
{
"error": {
"code": "BUDGET_EXCEEDED",
"message": "Amount exceeds mandate per-call ceiling.",
"retryable": false,
"stage": "validation",
"fieldErrors": {},
"programError": {
"programId": "C5K5LF7CGN5zKf7mxHxy5PYQHnvzHEui7dtkLZ1ytmb9",
"name": "PerCallCapExceeded",
"number": 6008
},
"retryAfterSeconds": 5,
"requestId": "req_..."
}
}Tova-specific error codes
| Code | HTTP status | Meaning |
|---|---|---|
PAYMENT_REQUIRED | 402 | Endpoint requires an X-Tova-Settlement header |
MANDATE_REVOKED | 409 | Mandate has been revoked |
MANDATE_EXPIRED | 409 | Mandate expirySlot has passed |
NULLIFIER_USED | 409 | Nullifier has already been spent |
SETTLEMENT_NOT_OPEN | 409 | Escrow is already Claimed or Refunded |
SETTLEMENT_NOT_EXPIRED | 409 | Refund attempted before deadlineSlot |
BUDGET_EXCEEDED | 422 | Amount exceeds per-call cap, epoch budget, or vault balance |
PROVIDER_CAPACITY_EXCEEDED | 422 | Provider unsettled volume exceeds stakedCapacityLamports |
ATTESTATION_INVALID | 422 | TEE receipt signature failed verification |
Base error codes
VALIDATION_ERROR (400), UNAUTHORIZED (401), ORIGIN_NOT_ALLOWED (403), NOT_FOUND (404), PROGRAM_UNAVAILABLE (409), CONFIGURATION_REQUIRED (409), IDEMPOTENCY_CONFLICT (409), TRANSACTION_EXPIRED (409), PAYLOAD_TOO_LARGE (413), UNSUPPORTED_MEDIA_TYPE (415), SIMULATION_FAILED (422), CHAIN_REFUSED (422), RATE_LIMITED (429), INTERNAL_ERROR (500), UPSTREAM_UNAVAILABLE (502).