# Agent Verification Utility auth.md

## Agent audience and access model

This document is for autonomous software agents and their operators. The verification service is intentionally anonymous: account registration, an API key, OAuth, OpenID Connect, cookies, and a login session are not required for discovery, quotes, or paid execution.

Free discovery, documentation, health, aggregate statistics, revenue-goal status, quotes, MCP `tools/list`, and the four free MCP tools can be called without credentials. The complete public contract is at https://agent-economy.kgninja.dev/openapi.json.

## Optional anonymous agent registration

Registration is optional and does not grant application access or authorize payment. An agent that needs a short-lived, verifiable service-local identity can provision one without an email address, account, API key, or human contact.

- Registration endpoint: `POST https://agent-economy.kgninja.dev/agent/register`
- Registration method: `anonymous`
- Request content type: `application/json`
- Request body: `{}`
- Credential type: `urn:kgninja:params:agent-credential:anonymous-registration-receipt`
- Credential lifetime: 15 minutes
- Claim endpoint: `GET https://agent-economy.kgninja.dev/agent/registration`

The registration response returns a signed short-lived bearer credential once. To inspect its active claim, send it only to this service as `Authorization: Bearer <credential>` on the claim endpoint. The credential can read only its own registration claim. It cannot call paid work without x402, cannot bypass rate limits, and is not accepted as wallet or payment authorization. There is no revocation endpoint because the receipt has no application privileges and expires after 15 minutes; discard it to stop using it.

```json
{
  "agent_auth": {
    "skill": "anonymous",
    "register_uri": "https://agent-economy.kgninja.dev/agent/register",
    "identity_types_supported": ["anonymous"],
    "anonymous": {
      "credential_types_supported": [
        "urn:kgninja:params:agent-credential:anonymous-registration-receipt"
      ],
      "claim_uri": "https://agent-economy.kgninja.dev/agent/registration"
    }
  }
}
```

Example provisioning request:

```http
POST /agent/register HTTP/1.1
Host: agent-economy.kgninja.dev
Content-Type: application/json

{}
```

## Paid execution authorization

Only deterministic execution through `POST /verify-evidence` or the MCP `verify_evidence` tool is paid. The current price is 10000 atomic USDC ($0.01) on eip155:8453.

An unpaid execution returns an x402 v2 payment requirement. A caller should validate the scheme, network, asset, amount, receiving address, resource, and expiry against its own payment policy. If approved, it signs one requirement and retries the identical request with `PAYMENT-SIGNATURE` for HTTP or `_meta["x402/payment"]` for MCP.

The x402 signature authorizes only the advertised payment and request. It is not a reusable application credential, is independent of optional agent registration, and does not create an authenticated session. Preserve `PAYMENT-RESPONSE` or `_meta["x402/payment-response"]` as settlement proof.

## Credential and data handling

- Never send seed phrases, wallet private keys, API secrets, third-party bearer tokens, or unrelated personal data. Send this service's short-lived registration receipt only to its documented claim endpoint.
- Evidence must be bounded inline JSON. The service does not fetch caller-supplied URLs or execute caller code.
- Raw evidence is not retained in D1; only digests and the minimum transaction and audit metadata are stored.
- Verify returned evidence with https://agent-economy.kgninja.dev/.well-known/jwks.json.

## Machine-readable references

- MCP endpoint: https://agent-economy.kgninja.dev/mcp
- A2A Agent Card: https://agent-economy.kgninja.dev/.well-known/agent-card.json
- A2A JSON-RPC endpoint: https://agent-economy.kgninja.dev/a2a
- Optional anonymous registration: https://agent-economy.kgninja.dev/agent/register
- Registration claim: https://agent-economy.kgninja.dev/agent/registration
- x402 discovery: https://agent-economy.kgninja.dev/.well-known/x402
- Agent manifest: https://agent-economy.kgninja.dev/agent.json
- Revenue goal status: https://agent-economy.kgninja.dev/.well-known/revenue-goal.json
- OpenAPI 3.1: https://agent-economy.kgninja.dev/openapi.json
- Security and trust boundary: https://agent-economy.kgninja.dev/docs/security-and-trust

OAuth authorization-server and protected-resource metadata are intentionally not published because this is not an OAuth-protected resource. The optional anonymous registration receipt is not an OAuth access token. Absence of OAuth metadata must not be interpreted as permission to skip the x402 payment policy for paid execution.