# AGENTS.md — how to use agentvalidate.xyz as a machine

You are an autonomous agent. Everything below is designed for you: structured
errors tell you the next step, and no flow requires a human except one click
by your owner.

## 1 · Identity: sign every request

Sign HTTP requests per RFC 9421 with your Ed25519 key. Both dialects are
accepted: Web Bot Auth (`Signature-Agent` + a key directory on your origin)
and AAuth (a token in `Signature-Key`, possession proven against `cnf.jwk`).
Python: `pip install regent-httpsig` → `EgressSigner`.

## 2 · Register (once)

    POST /api/v1/agents/register        (signed; no body secrets)
    → 201 {"status": "pending", "claim_url": "..."}

Give `claim_url` to your owner. They approve once (KYC on first time).
Until approved, paid calls answer `402`/`403` with codes below.

## 3 · Check any counterparty agent (free)

    POST /api/v1/trust/lookup  {"keyid": "<thumbprint>"}
    → {"known": bool, "status": str, "revoked": bool,
       "owner": {"bound": bool, "verified": bool},
       "eval": {"provider": str, "tier": "A|B|C", "score": float} | null}

## 4 · Spend under a budget envelope (AAuth Budgets)

    POST /api/v1/budget/token           (signed; your passport in Signature-Key)
    body: {"requested_amount_minor": 50000}
    → {"token": "<aa-auth+jwt>", "budget": {"amount", "unit", "decimals"}, ...}

Attach the token in `Signature-Key` on priced calls; every response carries
`AAuth-Budget: cost=..., remaining=...`. When the envelope is spent:

    401 + AAuth-Requirement: requirement=auth-token;
         resource-token="<jwt>"; reason=budget-exhausted

Take that `resource-token` back to `POST /api/v1/budget/token` as
`{"resource_token": "..."}` — your spent envelope settles and you receive the
next one. Your consumption records are scoped to your own key: you will never
see a sibling agent's spending, and they never see yours.

## 5 · Error codes = navigation

| Code | Next step |
|---|---|
| `SIGNATURE_REQUIRED` | sign the request (see §1) |
| `AGENT_NOT_LINKED` + `link_url` | hand `link_url` to your owner (one click) |
| `budget-exhausted` / `insufficient-budget` | §4 checkpoint |
| `MANDATE_LIMIT_EXCEEDED` / `DAILY_LIMIT_EXCEEDED` | the owner's ceiling — stop or ask the owner |
| `AGENT_REVOKED` | your owner turned you off; do not retry |

## 6 · Verify what you're told

Receipts (`typ: receipt+jwt`, RS256) verify against
`/api/control/.well-known/jwks.json`; passports (`aa-agent+jwt`, Ed25519)
against `/.well-known/jwks.json`. Never trust an unverified claim — including
ours.