H-Series H-Index H-Seal H-Grant H-Relay Contact
H-Grant

Docs

The public H-Grant API. Base URL https://h-grant.xr-utilities.ai. Responses are JSON. Owner actions are authorized with a structured-data signature, never a raw signature over a bare payload. The enforcement internals (vault, key release, broker, cap accounting) are not part of the public surface and are out of scope here.

Endpoints

GET /health

Liveness. Returns status and version.

GET /config

Public configuration: topic IDs, HCS mode, x402 mode, price in US cents, approved chains (CAIP-2), and available adapters.

POST /vault/deposit

Owner-signed. Deposits a credential (or, in enclave mode, an owner-sealed credential). The owner signs a canonical body binding the vault, owner identity, adapter, a hash of the credential, a nonce, and a timestamp. The raw credential is sealed at rest.

POST /grant/publish

Owner-signed. Publishes a grant authorizing a grantee to take specific actions within caps, until an expiry. Verified, then anchored to the grant topic. 

POST /grant/publish
{
  "grantId": "grant-001",
  "vaultId": "vault-abc",
  "granteeIdentity": "eip155:8453:0xAgent…",
  "ownerIdentity": "hedera:mainnet:0.0.1234",
  "allowedActions": ["stripe:charge"],
  "targetAllowlist": ["acct_123"],
  "caps": { "perCallUsdCents": 500, "dailyUsdCents": 5000 },
  "requiredAttestations": [],
  "validUntil": 1790000000,
  "issuedAt": 1789990000,
  "nonce": "a1b2c3",
  "signatureScheme": "tip712",
  "ownerSignature": "0x…",
  "ownerPublicKey": "302a…"
}

POST /grant/revoke

Owner-signed. Revokes a grant. Honored on every subsequent release check and anchored to the grant topic.

POST /call/:vaultId

The release call. With payment enforced, an unpaid call returns a standard x402 402 challenge; retry with the payment envelope in the X-Payment header. On success the upstream result is returned, never the credential. 

POST /call/:vaultId        (X-Payment: <x402 envelope>)
{
  "granteeIdentity": "eip155:8453:0xAgent…",
  "action": "stripe:charge",
  "targetId": "acct_123",
  "payload": { /* forwarded to the upstream adapter */ }
}
HTTP 402 Payment Required
{
  "x402Version": 2,
  "accepts": [
    {
      "scheme": "exact",
      "network": "hedera-mainnet",
      "asset": "0.0.456858",
      "amount": "50000",
      "payTo": "0.0.10490145",
      "maxTimeoutSeconds": 300,
      "extra": { "tokenDecimals": 6 }
    }
  ]
}

GET /audit/:vaultId

Owner-signed read of a vault's audit events. The owner signs a canonical body carried in headers, within a 300-second freshness window. (For public browsing, the audit topic can also be read directly from the mirror node, which is what the audit explorer does.) 

GET /audit/:vaultId?limit=50
x-owner-signature-scheme: tip712 | eip712 | ed25519
x-owner-signature: <signature over { vaultId, ownerIdentity, issuedAt, nonce }>
x-owner-public-key: <required for ed25519>
x-owner-issued-at: <unix seconds, within a 300s window>
x-owner-nonce: <string>

Signing

Owner actions are signed with one of three schemes: TIP-712 (Hedera), EIP-712 (EVM), or Ed25519. The signature covers a canonicalized JSON body (keys sorted, array order preserved), not the request envelope. Identities are CAIP-10 (for example hedera:mainnet:0.0.1234 or eip155:8453:0x…). For EVM schemes the address is recovered from the signature and must match the identity; for Ed25519 the public key is supplied alongside. Each signed body carries a nonce and timestamp for replay resistance.

Payment (x402)

Release calls settle a per-call fee through x402, the same multi-chain facilitator the H-Series shares. Pay in USDC or the native asset on Hedera, Base, XRPL, or Solana. See pricing.

On-chain message formats

Grants and revocations are published to the grant topic; audit events to the audit topic. An audit event carries no secret, and target identifiers are stored as a SHA-256 hash. 

// audit topic message
{
  "v": 1,
  "id": "…",
  "vaultId": "vault-abc",
  "grantId": "grant-001",
  "grantee": "eip155:8453:0xAgent…",
  "action": "stripe:charge",
  "targetIdHash": "<sha256 hex, never plaintext>",
  "amountUsdCents": 100,
  "result": "released",
  "reason": null,
  "at": 1789990500
}