api

The Halot server exposes REST endpoints for quoting, job preparation and funding confirmation, provider and verifier operations, facilitator flows for the SDK middleware, and basic health status.

Authentication

Halot uses two header families: payment headers for requester funding flow and actor-signed headers for provider or verifier actions.

bash
# Payment flow
PAYMENT-REQUIRED: <base64 PaymentRequirement>
PAYMENT-SIGNATURE: <base64 PaymentAuthorization>
x-halot-receipt: <jobId>

# Actor auth
x-halot-actor-id: prov_... | ver_...
x-halot-actor-address: 0x...
x-halot-actor-role: provider | verifier
x-halot-actor-timestamp: 2026-04-08T12:00:00.000Z
x-halot-actor-signature: 0x...

Quote & Prepare

POST /quote

Returns a non-binding quote for a service and input payload.

POST /jobs/prepare

Without PAYMENT-SIGNATURE, returns 402 with the encoded payment requirement. With a valid signature, returns the prepared job definition that must be funded on-chain.

json
// POST /quote
{
  "serviceId": "svc_...",
  "input": { "query": "halot" },
  "requesterAddress": "0x..."
}

// POST /jobs/prepare
{
  "quoteId": "q_...",
  "settlementAddress": "G..." // required for stellar:* networks
}

Jobs

RoutePurpose
POST /jobsConfirms a funded prepared job using prepareId and transactionHash.
GET /jobsLists jobs in reverse chronological order.
GET /jobs/:jobIdReturns the full job record, including result, attestations, and settlement state.
GET /jobs/:jobId/resultReturns the result, attestations, settlement, and current job status.
POST /jobs/:jobId/resultProvider submits output. Requires provider actor auth headers.
POST /jobs/:jobId/attestVerifier submits an attestation. Requires verifier actor auth headers.
POST /jobs/:jobId/escalatePromotes an already escalated job to the next trust tier and reselects a fresh jury.

Providers & Services

Provider registration is public. Assignment fetch and stream routes require provider actor auth, and stream routes also require x-halot-worker-id.POST /providers/registercreates only the provider identity and anchors the provider config hash onchain; services are registered later through the provider-scoped service routes.

bash
GET    /providers
GET    /providers/:providerId
GET    /providers/:providerId/stats
GET    /providers/:providerId/jobs/next
GET    /providers/:providerId/jobs/stream
POST   /providers/register
PUT    /providers/:providerId
POST   /providers/:providerId/identity

GET    /services/:serviceId
GET    /providers/:providerId/services
POST   /providers/:providerId/services
PUT    /providers/:providerId/services/:serviceId
DELETE /providers/:providerId/services/:serviceId

Verifiers

Verifier registration is public. Job assignment fetch and stream routes require verifier actor auth, and stream routes use the same worker lease header as providers.

bash
GET  /verifiers
GET  /verifiers/:verifierId
GET  /verifiers/:verifierId/stats
GET  /verifiers/:verifierId/jobs/next
GET  /verifiers/:verifierId/jobs/stream
POST /verifiers/register
POST /verifiers/:verifierId/identity

Facilitator

These routes back the exported halot()middleware. They are used when requesters talk directly to provider endpoints instead of calling the aggregator job flow themselves.

bash
POST /facilitator/quote   // returns quote + paymentRequired
POST /facilitator/verify  // checks x-halot-receipt jobId
POST /facilitator/report  // provider reports output with actor auth

Operations

bash
GET /health
GET /status/uptime