Reference

REST API

Complete HTTP endpoint, schema, authentication, SSE stream, and error envelope reference for the Tova Hono API.

Base URL and contract version

SettingValue
Default local API URLhttp://127.0.0.1:37402
Contract package@tova/contract (0.1.0)
Allowed custom headersX-Fixture, X-Fixture-Session, X-Tova-Settlement, Authorization, Last-Event-ID, solana-client
Exposed response headersX-Tova-Quote, X-Tova-Receipt

All build endpoints return an unsigned versioned (v0) Solana transaction in TxBuildResponse:

json
{
  "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

MethodPathDescription
GET/healthReturns { status, mode, cluster, programId, asOf } (status is ready, waiting, or fixture)
GET/v1/protocol/statsReturns ProtocolStats including counters, feeBps, feeRecipient, token, and pdaLayout
GET/v1/eventsServer-Sent Events (SSE) stream of indexed protocol events; supports Last-Event-ID
POST/rpcSolana JSON-RPC relay (enabled in chain mode)

Authentication (SIWS)

MethodPathDescription
GET/auth/nonceIssues a Sign-In With Solana nonce (statement: "Sign in to Tova Protocol")
POST/auth/verifyVerifies signed SIWS payload and returns session token (Authorization: Bearer <token>)
GET/auth/sessionReturns active session state
POST/auth/logoutInvalidates active session

Shielded Ring Vaults

MethodPathQuery / BodyResponse
GET/v1/vaultsQuery: principal?, mint?, cursor?, limit?VaultsPage
GET/v1/vaults/:vaultPath: vault PDAVaultDetail (includes notes[])
POST/v1/vaults/buildCreateVaultRequest (alias: POST /api/vaults/build)TxBuildResponse
POST/v1/vaults/:vault/deposit/buildDepositShieldedRequestTxBuildResponse
POST/v1/vaults/:vault/withdraw/buildWithdrawShieldedRequestTxBuildResponse

CreateVaultRequest

FieldTypeRequired
principalSolana AddressYes
mintSolana AddressYes
viewingKeyTagHex32 (64 hex chars)Yes
auditorKeyTagHex32No
initialDepositLamportsU64 decimal stringNo
initialCommitmentHex32No
initialCiphertextstring (max 4096 chars)No

DepositShieldedRequest

{ principal: Address, amountLamports: PositiveU64, commitment: Hex32, ciphertext?: string }

WithdrawShieldedRequest

{ principal: Address, amountLamports: PositiveU64, nullifierHash: Hex32, proofBase64?: Base64 }

Shielded Mandates

MethodPathQuery / BodyResponse
GET/v1/mandatesQuery: vault?, principal?, agent?, status? (Active, Revoked, Expired)MandatesPage
GET/v1/mandates/:mandatePath: mandate PDAMandateItem
POST/v1/mandates/buildIssueMandateRequestTxBuildResponse
POST/v1/mandates/:mandate/revoke/build{ principal: Address }TxBuildResponse

IssueMandateRequest

FieldTypeRequired
principalAddressYes
vaultAddressYes
agentAddressYes
mandateIdU64 decimal stringNo
perCallCapLamportsPositiveU64Yes
epochBudgetLamportsPositiveU64Yes
epochDurationSlotsinteger (10..50000000)Yes
allowedProviderAddressNo
expirySlotpositive integerYes
auditorKeyTagHex32No

Attested Providers

MethodPathQuery / BodyResponse
GET/v1/providersQuery: hardwareType? (IntelTDX, AmdSevSnp, LocalAttested)ProvidersPage
GET/v1/providers/:providerPath: provider PDA or providerPubkeyProviderItem
POST/v1/providers/buildRegisterProviderRequestTxBuildResponse
POST/v1/providers/:provider/attestation/buildUpdateProviderAttestationRequestTxBuildResponse

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

MethodPathQuery / BodyResponse
GET/v1/settlementsQuery: vault?, mandate?, provider?, status? (Open, Claimed, Refunded)SettlementsPage
GET/v1/settlements/:settlementPath: settlement PDA or settlementIdSettlementItem
POST/v1/settlements/open/buildOpenSettlementRequestTxBuildResponse
POST/v1/settlements/:settlement/claim/buildClaimSettlementRequestTxBuildResponse
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

MethodPathBody / ParamsResponse
POST/v1/transactions/submit{ id: string, signedTransactionBase64?: Base64, signature?: Signature }TxStatusResponse
GET/v1/transactions/:idPath: build idTxStatusResponse

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):

json
{
  "prompt": "Summarize shielded 402 receipt verification",
  "model": "tova-tee-llama-3-8b",
  "mandate": "<optionalMandatePda>"
}
  • Without `X-Tova-Settlement`: Returns HTTP 402 with X-Tova-Quote header and { error: { code: "PAYMENT_REQUIRED", ... }, quote }.
  • With `X-Tova-Settlement: <settlementId>`: Verifies the Open settlement, signs a real Ed25519 TEE receipt, marks the settlement Claimed, and returns HTTP 200 with DemoInferSuccess (output, model, settlementId, settlementAddress, requestHash, responseHash, slot, attestationSignature, attestationPubkey, hardwareType, claimTxSignature, feeLamports, encryptedReceipt).

Error envelope and codes

Every failed response returns:

json
{
  "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

CodeHTTP statusMeaning
PAYMENT_REQUIRED402Endpoint requires an X-Tova-Settlement header
MANDATE_REVOKED409Mandate has been revoked
MANDATE_EXPIRED409Mandate expirySlot has passed
NULLIFIER_USED409Nullifier has already been spent
SETTLEMENT_NOT_OPEN409Escrow is already Claimed or Refunded
SETTLEMENT_NOT_EXPIRED409Refund attempted before deadlineSlot
BUDGET_EXCEEDED422Amount exceeds per-call cap, epoch budget, or vault balance
PROVIDER_CAPACITY_EXCEEDED422Provider unsettled volume exceeds stakedCapacityLamports
ATTESTATION_INVALID422TEE 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).