# auth.md

You are an agent. `intel.twzrd.xyz` supports **agentic registration**: discover ->
pick a method -> register -> call the API. This service is permissionless and
anonymous -- a Solana wallet is your identity, an x402 USDC micropayment is your
registration, and the Ed25519-signed receipt you get back is your portable
credential. There is no OAuth token exchange, no account creation, and no claim or
revocation ceremony: the wallet you control is the only identity.

Follow the steps in order. Examples use the host `https://intel.twzrd.xyz`; substitute
the host you read this document from.

## Step 1 — Discover

Discovery is two hops, and a `402 Payment Required` you may already hold did the
first. A paid endpoint answers an unpaid request with `402` and a
`WWW-Authenticate` header pointing at the Protected Resource Metadata (PRM):

```http
HTTP/1.1 402 Payment Required
WWW-Authenticate: x402 resource_metadata="https://intel.twzrd.xyz/.well-known/oauth-protected-resource"
```

### 1a. Fetch the Protected Resource Metadata

```http
GET /.well-known/oauth-protected-resource
```

```json
{
  "resource": "https://intel.twzrd.xyz",
  "authorization_servers": ["https://intel.twzrd.xyz"],
  "bearer_methods_supported": ["header"],
  "resource_documentation": "https://intel.twzrd.xyz/auth.md",
  "x_auth_methods": ["x402"]
}
```

- `resource` -- the API you are calling.
- `authorization_servers` -- where the `agent_auth` block lives (Step 1b).
- `x_auth_methods` -- `["x402"]`: this service registers agents via payment, not
  OAuth bearer tokens.

### 1b. Fetch the Authorization Server metadata

```http
GET /.well-known/oauth-authorization-server
```

The `agent_auth` block is the part written for you:

```json
{
  "issuer": "https://intel.twzrd.xyz",
  "agent_auth": {
    "skill": "https://intel.twzrd.xyz/auth.md",
    "register_uri": "https://intel.twzrd.xyz/auth.md",
    "claim_uri": "https://intel.twzrd.xyz/v1/intel/trust/{pubkey}",
    "identity_types_supported": ["anonymous"],
    "anonymous": {
      "credential_types_supported": ["x402_payment_receipt"]
    }
  }
}
```

- `register_uri` -- this document.
- `identity_types_supported` -- `["anonymous"]` is the only method (Step 2).
- `anonymous.credential_types_supported` -- `x402_payment_receipt`: the credential
  you receive is a signed payment receipt.

## Step 2 — Pick a method

The decision tree has one branch: this service supports **`anonymous`**
registration only. You do not need a user identity, an ID-JAG, or an email. If
`identity_types_supported` in Step 1b does not list `anonymous`, stop -- but it
always will here.

## Step 3 — Register (anonymous)

Anonymous registration is implicit in the x402 payment cycle -- there is no
separate registration POST that returns a credential out of band. To register and
obtain a credential in one round trip:

1. Fund a Solana wallet with USDC. The per-request network fee can be sponsored
   (see the `feePayer` in the 402 challenge).
2. Call a paid endpoint. The server answers `402` with a challenge:

```http
GET /v1/intel/trust/{pubkey}

HTTP/1.1 402 Payment Required
X-PAYMENT-REQUIRED: {"network":"solana","asset":"USDC","amount":"0.05","recipient":"...","nonce":"..."}
```

3. Sign the challenge with your wallet and resend with an `X-PAYMENT` header:

```http
GET /v1/intel/trust/{pubkey}
X-PAYMENT: <base64 signed Solana payment for the challenge>
```

4. The server validates the payment, returns the response, and issues your
   credential in `X-PAYMENT-RECEIPT`:

```http
HTTP/1.1 200 OK
X-PAYMENT-RECEIPT: <base64 Ed25519-signed V6 receipt>
```

Use an x402-capable client that preserves the sponsored fee-payer slot semantics
in the 402 -> sign -> retry loop, or the MCP server at `https://intel.twzrd.xyz/mcp`.

AgentCash caveat (2026-06-23): `npx agentcash@latest fetch ...` is not currently
a green TWZRD paid-trust repro against the sponsored self-settle challenge. It
failed closed with `payment_invalid` / `fee_payer_slot_already_signed`, and the
AgentCash balance stayed unchanged. Treat AgentCash as a compatibility diagnostic
until it emits a transaction with the advertised sponsor fee-payer slot left
blank for TWZRD to co-sign.

## Step 4 — Use the credential

The signed receipt in `X-PAYMENT-RECEIPT` is portable and verifiable offline --
recompute the keccak leaf and check the Ed25519 signature against the issuer key
(`GET https://intel.twzrd.xyz/.well-known/twzrd-receipt-pubkey`), or POST it back for a
server-side check:

```http
POST /v1/receipts/verify
Content-Type: application/json

<the twzrd_receipt object>
```

## Claim and revocation

Not applicable. Registration is anonymous and the wallet you control is the
identity, so there is no claim ceremony to bind a user and no server-issued
credential to revoke. The `claim_uri` advertised in `agent_auth` simply points at
the paid trust endpoint where the credential is minted.

## Endpoints by access tier

| Tier | Example | Auth Required |
|------|---------|---------------|
| Free | `GET /v1/intel/preflight` | None |
| Free | `POST /v1/receipts/verify` | None |
| Free | `GET /health` | None |
| Paid | `GET /v1/intel/trust/{pubkey}` | x402 USDC payment |
| Paid | `GET /v1/intel/solana_market_*` | x402 USDC payment |

## How x402 works

1. Client makes a normal HTTP request to a paid endpoint.
2. Server responds **402 Payment Required** with a `X-PAYMENT-REQUIRED` header
   containing a JSON challenge (network, asset, amount, recipient, nonce).
3. Client signs the challenge with its Solana wallet and re-submits with
   a `X-PAYMENT` header containing the signed payment receipt.
4. Server validates the payment, processes the request, and returns
   a `X-PAYMENT-RECEIPT` header with a signed V6 receipt for auditing.

## Prices

| Resource | Price (USDC) |
|----------|-------------|
| Trust intel + signed receipt | 0.05 |
| Solana market data | 0.03 |
| All other endpoints | 0.00 |

## Keys and verification

Public key for receipt signature verification:
`GET https://intel.twzrd.xyz/.well-known/twzrd-receipt-pubkey`

x402 facilitator config:
`GET https://intel.twzrd.xyz/.well-known/x402`

## MCP (no payment required)

All tools are also available over **MCP Streamable HTTP** at:
`https://intel.twzrd.xyz/mcp`

MCP access is free — the server's own x402 identity costs are absorbed.