API documentation

Base URL: https://h-seal.xr-utilities.ai

All endpoints return JSON. Anchoring requires a TIP-712 signature and x402 payment header. Read endpoints are free and unauthenticated.

POST /anchor

Anchor a new receipt on Hedera Consensus Service. Requires a TIP-712/EIP-712 signed receipt payload and an x402 payment header.

Headers

Authorization: TIP-712 <signature>
X-Payment: <x402 envelope (base64)>
Content-Type: application/json

Request body

{
  "taskId": "string",
  "serviceEndpoint": "string",
  "requestHash": "string (hex)",
  "responseHash": "string (hex)",
  "resultStatus": "success | error | timeout | partial",
  "startedAt": 1717000000000,
  "completedAt": 1717000001000,
  "latencyMs": 1000,
  "callerIdentity": "string (CAIP-10)",
  "providerIdentity": "string (CAIP-10)",
  "receiptTopicId": "string",
  "issuedAt": 1717000001000
}

Response 200

{
  "id": "0.0.12345/42",
  "consensusTimestamp": "1717000001.123456789",
  "anchoredAt": 1717000001123
}

GET /receipts

List receipts. Supports filtering by caller, provider, or task ID.

Query parameters

?caller=hedera:mainnet:0.0.12345   Filter by caller identity (CAIP-10)
?provider=hedera:mainnet:0.0.67890 Filter by provider identity (CAIP-10)
?taskId=abc-123                    Filter by task ID
?cursor=<opaque>                   Pagination cursor
?limit=50                          Results per page (default 50, max 200)

Response 200

{
  "receipts": [ ... ],
  "nextCursor": "string | null"
}

GET /receipts/:id

Retrieve a single receipt by its ID (topic/sequence format, e.g. 0.0.12345/42).

Response 200

{
  "id": "0.0.12345/42",
  "taskId": "string",
  "serviceEndpoint": "string",
  "requestHash": "string",
  "responseHash": "string",
  "resultStatus": "success",
  "startedAt": 1717000000000,
  "completedAt": 1717000001000,
  "latencyMs": 1000,
  "callerIdentity": "hedera:mainnet:0.0.12345",
  "providerIdentity": "hedera:mainnet:0.0.67890",
  "anchoredAt": 1717000001123,
  "consensusTimestamp": "1717000001.123456789"
}

GET /config

Returns registry configuration including the receipt topic ID, fee amount, and accepted payment options.

GET /health

Liveness check. Returns 200 if the server process is running.

GET /ready

Readiness check. Returns 200 when the server is connected to Hedera and the local index is up to date.

Authentication and payment

TIP-712 signing

H-Seal uses TIP-712 (the Hedera-native variant of EIP-712 typed data signing) to authenticate receipt submissions. The caller constructs the receipt payload, computes a canonical hash, and signs it with their wallet. EIP-712 signatures from EVM wallets on Hedera are also accepted. The signature is passed in the Authorization header.

x402 payment

Payment for anchoring is handled via the x402 protocol. When a client sends an anchor request without payment, the server responds with 402 Payment Required and a payment options envelope. The client selects a payment method, constructs a signed transaction, and resubmits with an X-Payment header containing the base64-encoded x402 envelope.