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

Everything is self-serve: create a company account, issue your av_… key (you certify the purpose of access at issuance), and the console walks you to your first live lookup — it flips to LIVE the moment your server sends one. Then wire two things:

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 /t/v1/trust/lookup          (Authorization: Bearer av_…)
{"keyid": "<sig.keyid>"}

→ {"known": true, "status": "approved", "revoked": false,
   "owner": {"bound": true, "verified": true},
   "eval": {"provider": "RagMetrics", "tier": "A", "score": 0.93},
   "recommendation": {"action": "allow", "reason": "OK",
                      "mode": "enforce", "policy_version": 3}}

Your policy lives in the console, not in your code. Set the ladder once at /app → Policy (unknown / awaiting-owner / no-eval / minimum tier, plus per-agent pins) and every lookup answers with a recommendation computed from your rules — enforcement in your service is one line: if rec.action != "allow": deny(rec.reason). Change a threshold in the console and it applies on the next request, no deploy. Start in observe mode: recommendations are journaled on the Decisions page without binding you, then flip to enforce.

Fixed precedence: a revoked agent is always denied (the kill switch is not configurable) → your pins → your ladder. Reasons you'll see: AGENT_REVOKED · TENANT_BLOCKED · TENANT_PINNED · UNKNOWN_AGENT · AWAITING_OWNER · NO_EVAL · TIER_TOO_LOW · OK.

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 + creates their owner account,
#     then verifies identity once (Didit hosted KYC — documents stay with the 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 /t/v1/trust/lookup`	Tenant lookup (Bearer `av_…`): keyid → known / status / revoked / owner / eval, plus `recommendation` once your policy is set. Metered: one lookup = one decision.
`POST /api/v1/trust/lookup`	Public lookup (no key): registry facts only — no eval overlay, no recommendation.
`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).
`/t/v1/console/*`	Everything the console does — keys, policy, pins, webhooks (+test-fire, delivery log), usage, decisions journal — session-authenticated; the UI at /app is the reference client.
`/t/v1/owner/*`	Owner surface: claim preview/approve, Didit KYC start/status, the owner's agents + revoke. Owners are agentvalidate accounts — no marketplace account anywhere in the path.

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).