API documentation

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

All endpoints return JSON. Creating a ring requires a structured-data signature (TIP-712 / EIP-712 / Ed25519) and an x402 payment header. Every other action is free but still owner-signed. Read endpoints are unauthenticated except the resolved roster, which is served over an authenticated channel.

POST /rings

Create a ring. Requires a structured-data signed ring.create event and an x402 payment header ($5 to create). The create event is anchored on the H-Pact HCS topic, signed and permanent.

Headers

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

Event kinds

create      owner, governance mode, policy
admit       member commitment, role, optional expiry
admitBatch  many member commitments in one signed event
evict       member commitment, optional evidence
policy      new policy version
renew       member commitment, new expiry
retire      terminal ring closure

POST /rings/:ringId/members

Admit or evict a member with an owner-signed admit, admitBatch, or evict event. On chain the ring stores a salted commitment (hash(identity, salt)), not the raw identity. Free.

GET /rings/:ringId

Read a ring's public state: its governance mode, policy version, and the signed commitments. The public view verifies the set is legitimate and complete without revealing who is in it. The resolved roster (identities and each member's standing) is read separately over the authenticated member channel, so the membership check is not an open oracle that defeats the salt.

Standing values

active      a member in good standing
probation   admitted but watched
suspended   auto-demoted, reversible; access withheld
evicted     terminal removal

GET /config

Returns service configuration: the ring HCS topic ID (0.0.10587224), governance modes, roles, standing values, event kinds, the signing contract, pricing, and the accepted payment options across every approved chain.

GET /health

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

Signing and payment

Structured-data signing

Every ring event is authenticated with structured-data signing under the H-Pact domain (version 1). Three schemes are accepted: TIP-712, EIP-712, and Ed25519. Identities are CAIP-10. Signatures carry a 300-second freshness window, so a signed event cannot be replayed outside that window.

x402 payment

Ring creation is paid via the x402 protocol. A create request without payment returns 402 Payment Required with a payment options envelope; the client selects a method, constructs a signed transfer, and resubmits with an X-Payment header carrying the base64-encoded x402 envelope. Admit, evict, and every other action are free.

MCP tools

H-Pact is also exposed as MCP tools under the h_pact_* namespace via the shared H-Series MCP server at https://mcp.xr-utilities.ai/mcp, so an agent can create and govern rings through one connection alongside the rest of the suite.