Documentation

Everything here runs in production today. Machine agents: read llms.txt and AGENTS.md instead — every error response tells you what to do next.

Quickstart — SaaS / API platform

Verify agent signatures locally, then ask one question per agent. Two steps:

pip install regent-httpsig

from regent_httpsig import HttpsigVerifier
from regent_httpsig.fastapi import attach, SignatureDep

attach(app, HttpsigVerifier())          # verifies RFC 9421 (Web Bot Auth + AAuth)

@app.post("/v1/orders")
async def orders(sig = SignatureDep):   # sig.keyid, sig.trusted, sig.agent
    ...

Then decide with one lookup — free tier, no key:

POST https://agentvalidate.xyz/api/v1/trust/lookup
{"keyid": "<sig.keyid>"}

→ {"known": true, "status": "approved", "revoked": false,
   "owner": {"bound": true, "verified": true},
   "eval": {"provider": "RagMetrics", "tier": "A", "score": 0.93}}

A sane starting policy: unsigned → rate-limit; known + owner.verified → normal access; eval tier A/B → raised limits. Money actions: add the governance tier (mandate check before your charge, signed receipt after) — pricing.

Quickstart — agent builder

One validation, accepted everywhere that checks. Four steps, ~30 minutes:

pip install regent-httpsig
regent-httpsig keygen                    # 1 · your Ed25519 key (keep the seed)

# 2 · register by signature — no API keys anywhere
POST https://agentvalidate.xyz/api/v1/agents/register   (RFC 9421-signed)
→ {"status": "pending", "claim_url": "https://…/claim/…"}

# 3 · your owner opens claim_url, approves (KYC once, with a licensed provider)
# 4 · evaluation by RagMetrics runs → your passport goes VALID, tier assigned

Then put the badge in your README — it links to your public passport page:

<a href="https://agentvalidate.xyz/passport/<your-keyid>">
  <img src="https://agentvalidate.xyz/badge/<your-keyid>.svg"></a>

API reference

Endpoint	What it does
`POST /api/v1/trust/lookup`	keyid → known / status / revoked / owner / eval. Public, free tier.
`POST /api/v1/agents/register`	Self-registration by RFC 9421 signature → pending + claim_url.
`POST /api/v1/budget/token`	Request a spending envelope (AAuth Budgets auth token). Signed; passport in `Signature-Key`. Bring the resource token from a refusal to settle and get the next slice.
`POST /api/v1/call/{listing}`	A governed, priced call — per-decision or against a budget envelope.
`GET /api/v1/receipts/{decision_id}`	The evidence pack for one decision (signed tokens).

Error codes are the interface

Code	Meaning · what to do
`401 SIGNATURE_REQUIRED`	Sign the request (RFC 9421). The body says how.
`401 AGENT_NOT_LINKED`	First contact with this SaaS — the response carries `link_url`; the owner clicks once.
`401 + AAuth-Requirement: reason=budget-exhausted`	Envelope spent. Take the `resource-token` from the header back to `/api/v1/budget/token`.
`403 MANDATE_LIMIT_EXCEEDED / DAILY_LIMIT_EXCEEDED`	The owner's ceiling said no — before any money moved.
`403 AGENT_REVOKED / AGENT_NOT_APPROVED`	The kill switch. Publicly visible in lookup within seconds.

Payment rails

The authorization layer is one; the money leg is swappable. Integrate once, upgrade rails freely.

Card-on-file (your existing billing) — available now

For agents acting for your existing customers: a one-time link (keyid ↔ customer), then our gate answers the one question your billing can't — did the human authorize this agent to do this — and you charge the saved card through your own PSP exactly as today. You change one line: read X-Regent-Customer instead of a session.

Stablecoin per-call (x402) — available now

For agents with no account at your service: your API answers 402 with machine-readable payment requirements; the agent pays USDC from its own wallet; our Governed Facilitator enforces the owner's mandate before settlement and mints the receipt. You provide a wallet address — nothing else. Funds move wallet-to-wallet; we never hold them.

Card-network agentic tokens — roadmap

Visa TAP and Mastercard Agent Pay tokenize the owner's card for a specific agent. Same gate, same receipts — the rail upgrades under the same integration when the network programs open up.

Standards

RFC 9421 HTTP Message Signatures (final) · Web Bot Auth (what OpenAI ships; both Signature-Agent wire forms) · AAuth -11 (agent / person / auth tokens, fully-specified algorithms per RFC 9864) · AAuth Budgets — we run the first known implementation, both roles, in production. Verifier is open source: regent-httpsig (PyPI).