H-Series
H-Agent
Provision an agent

API documentation

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

All endpoints return JSON. Owner-bound routes require the owner's credential: an OIDC access token as Authorization: Bearer, or a wallet SIWE credential as X-Wallet-Authorization. The backend runs on Base mainnet; the agent's key is held in a secure enclave and H-Agent never takes custody.

GET /config

Public configuration: network, whether the signer and MCP are enabled, and the cap policy (maximum cap and default cap period).

Response 200
{
  "service": "h-agent",
  "network": "base",
  "signerEnabled": true,
  "mcpEnabled": true,
  "policy": { "maxCapUsdCents": 5000, "defaultCapPeriodDays": 1 },
  "fee": { "enabled": true, "takeRatePercent": 3, "firstPartyExempt": true }
}
POST /agents/provision

Mint an owner-bound agent. The backend verifies the owner credential, mints the agent and owner smart accounts, sets a default on-chain backstop cap, and returns the agent identity plus a per-consumer MCP connection token.

Request body
{
  "label": "string (optional; names the agent)",
  "ownerModel": "embedded | connected (optional)"
}
Response 201
{
  "agentIdentity": "string (CAIP-10)",
  "agentSmartAddress": "0x...",
  "ownerSmartAddress": "0x...",
  "label": "string",
  "network": "base",
  "spendingAuthorized": false,
  "cap": { "allowanceUnits": "string", "periodDays": 1 },
  "connectionToken": "string",
  "mcpUrl": "string"
}
GET /agents

List every agent in the authenticated owner's fleet, newest first, each with its current MCP connection.

POST /agents/:address/apply-grant

Materialize an H-Grant grant as the agent's on-chain spend cap. The owner creates a grant in H-Grant naming the agent by its CAIP-10 identity, then applies it here by grant id. Returns the updated agent (now spendingAuthorized).

POST /agents/:address/refresh-cap

Connected-owner path: after the consumer grants a Spend Permission to the agent from their own wallet, the backend reads the live on-chain permission and persists it as the agent's cap.

POST /agents/:address/rotate

Rotate one agent's connection. The old MCP connection string stops working and a fresh one is returned. Every other agent is unaffected.

POST /agents/:address/retire

Retire one agent (soft delete): it leaves the fleet, its connection stops working, and its on-chain cap and H-Cert roster claim are revoked.

GET /agents/events

The owner's lifecycle audit trail (provisioned, rotated, retired, granted), newest first. Each event carries its HCS anchor reference when anchored.

POST /agents/:address/kyapay-token

Mint a Know Your Agent (KYA) token (the open KYAPay standard) for one of the owner's agents, bound to a merchant audience, so the merchant can admit the agent at checkout instead of blocking it as a bot. The pay claim reflects the live on-chain cap. By default the identity field carries a per-merchant relay address (no personal data); pass discloseRealIdentity: true to also include the owner's verified email and name (consent only, and only when the source email is verified). Owner-authenticated and agent-scoped.

POST /tokens/verify

Verify a KYA token from this issuer. The signature is ES256-pinned and the issuer, audience, and expiry are checked; an optional proof-of-possession signature confirms the presenter controls the agent's key. Returns valid plus the claims, or valid: false with a generic reason.

GET /.well-known/jwks.json

The issuer public key (ES256 / P-256) any relying party uses to verify a KYA token. Returns an empty key set until the issuer is configured.

GET /health GET /ready

Liveness and readiness checks. /health returns 200 if the process is running; /ready returns 200 when the store is reachable.

MCP tools

H-Agent is also exposed as MCP tools under the h_agent_* namespace via the shared H-Series MCP server at https://mcp.xr-utilities.ai/mcp. An agent connects with its per-consumer connection token, then can check who it is, read its remaining cap, quote, and pay, all within the owner-signed limit. A real-time detector runs over each action and emits a risk signal onto the shared H-Series audit topic that feeds the agent's H-Cert standing; before spending, the agent self-gates on that standing and holds off when its own tier has degraded. This is advisory and fail-soft, above the on-chain cap that stays the hard limit.