H-Agent: agent runtime identity and capped spend

H-Agent is the runtime identity layer of the H-Series. It gives a consumer’s AI agent (on Claude, ChatGPT, Grok, or Gemini) an identity the agent actually holds and the ability to act under an owner-set spend cap. The owner signs a USDC spending cap on Base and H-Agent mints the agent an MPC-held wallet under that owner-signed, on-chain Spend Permission. The owner keeps the funds; the cap is enforced on chain by the Spend Permission Manager contract, not by the operator. H-Agent holds no raw key and takes no custody. An over-cap transaction reverts on chain. It runs on Base mainnet.

What it does

• An identity the agent holds. The agent’s key is an MPC-held Coinbase CDP Server Wallet in a Trusted Execution Environment. H-Agent never holds a raw key or consumer funds.
• An on-chain cap. The owner signs a CDP Spend Permission (a USDC cap on Base). Spend is enforced on chain; an over-cap request reverts. The cap is the hard limit.
• A fleet. One owner can hold many agents; each distinct name is a distinct agent, listed newest first, each with its own MCP connection and spend authorization state.
• Merchant admission. H-Agent issues a KYA token (open KYAPay standard) bound to a merchant audience, so a merchant can admit the agent at checkout rather than block it as a bot. It shares no personal data unless the owner consents.
• Advisory self-gating. 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 holds off when its own tier has degraded. This is advisory and fail-soft, above the on-chain cap that stays the hard limit.

Using it from the showroom

The showroom is at h-series.xr-utilities.com/agent. It is for a person provisioning an agent and setting its cap.

1. Sign in. Sign in with Google or connect a wallet. Your credential is what binds the agent to you as its accountable owner.
2. Provision an agent. Use the “Provision an agent” action and name it. H-Agent mints the agent’s identity (and, for the embedded model, an owner smart account). Provisioning mints the identity only; the agent can spend nothing yet.
3. Set the cap. Grant spending by authorizing a USDC cap. On the standard path, author the capability policy in H-Grant and apply that grant to the agent; on the advanced path you set a cap directly. Either way the cap becomes an on-chain Spend Permission.
4. Connect it to Claude. Copy the per-consumer MCP connection string and paste it into your assistant. The token scopes the assistant to your agent only; it can never act for another.
5. Manage the fleet. Watch spend against the cap, rotate a connection (the old string stops working), or retire an agent (it leaves the fleet, its connection stops working, and its on-chain cap and H-Cert claim are revoked).

Using it from an agent (the backend)

The backend is at h-agent.xr-utilities.ai. 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 runtime paths for the agent itself run over MCP, scoped by the per-consumer connection token.

Owner-side provisioning:

POST https://h-agent.xr-utilities.ai/agents/provision
  Authorization: Bearer <owner OIDC token>
  { "label": "researcher", "capUsdCents": 5000, "periodDays": 1 }
  -> 201 { "agentIdentity": "<CAIP-10>", "agentSmartAddress": "0x...",
           "spendingAuthorized": true, "cap": {...},
           "connectionToken": "...", "mcpUrl": "..." }

POST https://h-agent.xr-utilities.ai/agents/:address/apply-grant   (apply an H-Grant grant as the cap)
GET  https://h-agent.xr-utilities.ai/agents                        (the owner's fleet)
POST https://h-agent.xr-utilities.ai/agents/:address/rotate        (rotate the connection)
POST https://h-agent.xr-utilities.ai/agents/:address/retire        (soft-delete, revoke the cap)
GET  https://h-agent.xr-utilities.ai/config                        (network, cap policy)

capUsdCents is optional: absent provisions the identity with no spend permission (pay fails closed until a cap is granted); a value mints the cap immediately. To materialize an H-Grant grant as the cap, create the grant in H-Grant naming the agent by its CAIP-10 identity, then POST /agents/:address/apply-grant.

The agent itself does not call these owner routes. It connects to H-Agent’s own MCP surface at https://h-agent.xr-utilities.ai/mcp with its per-consumer connection token (H-Agent is not on the shared mcp.xr-utilities.ai passthrough; its runtime tools are served by H-Agent directly), then works within the cap: who_am_i (check its identity), remaining_cap (read what is left), quote, pay, and purchase (buy from an x402 merchant, still bounded by the on-chain cap; H-Agent adds a 3% fee on the merchant price, first-party estate apps exempt). Provisioning, listing, rotating, and reading the cap are free. A KYA token for merchant checkout is minted owner-side via POST /agents/:address/kyapay-token and verified by any relying party against GET /.well-known/jwks.json.

Reading an agent’s run history and funding balance

The console shows the same activity on every device the owner signs in on, because the run history and balance are read from the backend, not the browser. All three reads are owner-token gated and scoped to the owner’s own agents.

• Run history. GET /agents/:address/runs?limit=<1-50> (default 20) returns the agent’s recent runs newest first, each with its tool name, an args summary, whether it was paid, the amount, the outcome, the anchored receipt reference, and hasOutput. The output itself is not inlined.
• Per-run output. GET /agents/:address/runs/:runId/output returns the stored result for one run on demand, parsed back to JSON when it was stored as JSON. A run that is not the owner’s, or that saved no output, returns 404 (the two are indistinguishable on purpose).
• Funding balance. GET /agents/:address/funding-balance returns the funding account’s real USDC balance on Base (balanceUsdCents, balanceBaseUnits, fundingAddress). This is distinct from the cap: the cap is a spend ceiling, the balance is the money actually available. A paid run settles real USDC out of the funding account and fails when it is empty even if cap headroom remains. The read is fail-open (null balance) so a flaky RPC never breaks the fleet read.

GET https://h-agent.xr-utilities.ai/agents/:address/runs?limit=20
GET https://h-agent.xr-utilities.ai/agents/:address/runs/:runId/output
GET https://h-agent.xr-utilities.ai/agents/:address/funding-balance
  Authorization: Bearer <owner OIDC token>   (or X-Wallet-Authorization)

The lifecycle audit trail

Every identity-lifecycle event on an owner’s agents (provision, granted, rotate, retire) is recorded and, when HCS anchoring is live, anchored on the shared H-Series audit topic. GET /agents/events (owner-token gated, owner-scoped) returns those events newest first, each with the event name, the agent identity, the timestamp, a payload hash, and, when anchored, its HCS sequence and consensus timestamp. The anchoring field is hcs when anchored on chain or local when the topic is not configured.

GET https://h-agent.xr-utilities.ai/agents/events
  Authorization: Bearer <owner OIDC token>   (or X-Wallet-Authorization)
  -> { "anchoring": "hcs", "events": [ { "event": "provision", "agentIdentity": "...",
       "at": ..., "payloadHash": "...", "hcs": { "sequence": ..., "consensusTimestamp": "..." } } ] }

Refreshing a connected-wallet cap

On the connected model the owner grants the Spend Permission from their own wallet, so H-Agent has to read the new cap off chain rather than mint it. After granting (or changing) the permission in the wallet, the owner calls POST /agents/:address/refresh-cap and H-Agent reads the granted cap from the Spend Permission Manager and records it against the agent. The route is connected-only (an embedded agent returns 400 not_a_connected_owner), and if no permission has been granted (or it was revoked) it returns 404 no_cap_granted_on_chain. On success it returns the agent’s updated public state.

POST https://h-agent.xr-utilities.ai/agents/:address/refresh-cap
  X-Wallet-Authorization: <owner SIWE credential>
  -> 200 { agent public state incl. the on-chain cap }   |   400 not_a_connected_owner   |   404 no_cap_granted_on_chain

Reading the public config

GET /config is an unauthenticated read of the deployment’s non-secret operational facts: the network, whether the signer and MCP are enabled, and the policy ceilings (maxCapUsdCents, defaultCapPeriodDays). It also carries the fee block a client reads to quote a purchase up front: takeRateBps (and takeRatePercent), gasMarkupCents, and whether the fee is enabled. The fee is added on top of the merchant price; first-party estate apps are exempt.

GET https://h-agent.xr-utilities.ai/config
  -> { "service": "h-agent", "network": "...", "signerEnabled": ...,
       "policy": { "maxCapUsdCents": ..., "defaultCapPeriodDays": ... },
       "fee": { "enabled": ..., "takeRateBps": ..., "takeRatePercent": ..., "gasMarkupCents": ... } }

Verifying a KYA token

A relying party (a merchant admitting an agent at checkout) verifies a KYA token against the issuer JWKS, and H-Agent also hosts a verify helper restricted to its own issuer, so there is no outbound JWKS fetch to configure. POST /tokens/verify takes { token, expectedAudience, expectedTyp? } and checks the signature, type, issuer, audience, and expiry. It returns 200 { valid: true, typ, claims, popChallenge } for a good token or 200 { valid: false, reason } for a bad one (a relying-party outcome, not a server error; reasons are generic so nothing about the key leaks).

For proof of possession, pass pop: { signature }: the presenter signs the returned popChallenge with the agent’s bound key, and the verify checks that signature against the token’s cnf binding. The endpoint returns 503 kyapay_disabled when the issuer is not enabled on the deployment.

POST https://h-agent.xr-utilities.ai/tokens/verify
  { "token": "<KYA JWT>", "expectedAudience": "merchant.example",
    "expectedTyp": "kya+jwt", "pop": { "signature": "0x..." } }
  -> 200 { "valid": true, "typ": "kya+jwt", "claims": {...}, "popChallenge": {...} }

Cross-device console chat sync

An owner can opt in to syncing their console conversations across devices. The catch that keeps this off the estate’s “no raw content server-side” line: every message is run through H-Gate redaction before it is stored, so raw PII never lands in storage, and redaction is fail-closed (if H-Gate is unavailable the write is refused rather than storing raw text). The store is a private per-owner convenience cache, never anchored and never a source of truth; the owner can delete it. All three write/read routes are owner-token gated and owner-scoped.

• GET /console/chat-sync/available reports whether sync is offered at all (H-Gate redaction configured); the client reads it to decide whether to show the toggle.
• GET /console/chats returns the owner’s synced conversations (redacted content), newest-updated first.
• PUT /console/chats pushes conversations ({ chats: [...] }, up to 30 chats, 500 messages each); it redacts every message and returns 503 chat_sync_unavailable if redaction is down.
• DELETE /console/chats/:id removes one conversation, scoped so it can only be the owner’s own.

GET    https://h-agent.xr-utilities.ai/console/chat-sync/available
GET    https://h-agent.xr-utilities.ai/console/chats
PUT    https://h-agent.xr-utilities.ai/console/chats        { "chats": [ { "id", "title", "content": { "messages": [...] } } ] }
DELETE https://h-agent.xr-utilities.ai/console/chats/:id
  Authorization: Bearer <owner OIDC token>   (or X-Wallet-Authorization)

How it composes

H-Agent pairs closely with H-Grant: H-Grant is where the owner authors the capability policy (allowed actions, limits, conditions, of which the spend cap is one dimension), and H-Agent materializes that grant as the agent’s on-chain spend authorization. An H-Agent identity can also publish an operated-by claim to H-Cert and pay for an H-Scope scan, all inside the same cap.

Owner funding: embedded vs connected

H-Agent supports two custody and funding models, materially different in UX and in who holds the money.

• Embedded (Google / SSO login). H-Agent provisions and manages a CDP funding account (an owner smart account) for the owner, so there is no wallet app to install. The owner tops it up, the agent spends within the cap, and the owner can withdraw unspent USDC back out.
• Connected (own wallet). The owner uses their own Coinbase Smart Wallet and grants the agent a Spend Permission from it; H-Agent reads the on-chain cap and mints only the agent. Funds never leave the owner’s wallet.

Both spend within the same on-chain cap. Provision the connected model with ownerModel: "connected" (requires wallet/SIWE auth).

Scheduled runs

An agent can run a tool on a recurring schedule instead of only on demand. Scheduling is free for free tools and paid per run for charged resources. The minimum interval is hourly (no sub-hourly), and an owner can hold up to 10 schedules. Due schedules fire on a cadence and anchor a receipt for each run, exactly like a manual run.

Owner-authed CRUD is at POST|GET|DELETE /x402-services/schedules; a cron executor fires the due ones.

The spend map

Because H-Agent signs every spend, it can record where each agent’s money went without the counterparty’s cooperation. Every completed purchase records the destination (the counterparty address, the resource host, the merchant, the chain, and the agent to merchant settlement reference).

The map reads back as a per-agent itinerary at GET /agents/:address/spend-map (owner-token gated), enriched read-time from the estate: the destination host is labeled against H-Index discovery, and the counterparty address carries its H-Cert standing tier (an arbitrary merchant reads “unrated”). The itinerary is split into in-estate and external hops. A bare pay cap pull has no merchant destination, so it records none.

Fields are public-safe only, and both enrichments degrade to null on a miss rather than failing the read.

KYA tokens for checkout

An owner can mint a Know Your Agent token (KYAPay, an ES256 JWT) bound to a specific merchant audience. The token reflects the agent’s live on-chain cap and proves the agent is bound to an accountable owner, so a merchant can admit it at checkout instead of blocking it as a bot. The merchant verifies it against the issuer JWKS; it shares no personal data unless the owner consents.

Minted owner-side via POST /agents/:address/kyapay-token and verified by any relying party against GET /.well-known/jwks.json. Off unless enabled.

Withdrawing unspent funds

An embedded agent’s owner can withdraw unspent USDC from the managed funding account to any Base address (POST /agents/:address/withdraw, { toAddress, amountUsdCents? }; an absent amount withdraws all). Withdrawal is gated by step-up auth: it requires a fresh re-sign, and a token older than the step-up window is rejected 403 step_up_required.

Connected agents do not need this path; the owner already holds the funds in their own wallet.

Sanctions hard-deny

Before any pay or purchase, the counterparty is checked against an embedded OFAC-SDN denylist. A match refuses the payment outright, before any funds move, and emits a public-safe audit event. The check is a local set-membership test keyed on the bare EVM address (so it holds on any eip155 chain) and never depends on a live sibling call; the list is refreshed weekly from the public OFAC SDN source.

This is a mandatory compliance floor, fail-closed, distinct from the advisory behavioral-standing signal above. It is the money-path mirror of the advisory OFAC overlay on an H-Cert standing read.

Where to go next

• Provision your first agent at h-series.xr-utilities.com/agent.
• Set the policy behind the cap with H-Grant.
• See how H-Agent fits the rest of the suite in Start here.