# 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. A paid endpoint answers an unpaid request with x402 v2
requirements in both the JSON body and the `payment-required` response header.
The standard Protected Resource Metadata (PRM) remains available at the path
below for agent scanners:

```http
HTTP/1.1 402 Payment Required
WWW-Authenticate: X402
payment-required: <base64-encoded x402 v2 PaymentRequired envelope>
```

### 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
payment-required: <base64-encoded x402 v2 PaymentRequired envelope>
```

Decode the envelope to inspect `accepts` (network, asset, amount, payTo,
feePayer, and recentBlockhash) before signing.

3. Sign one accepted requirement with your wallet and resend the same request
   with the x402 v2 `payment-signature` header:

```http
GET /v1/intel/trust/{pubkey}
payment-signature: <base64-encoded x402 v2 PaymentPayload>
```

4. The server validates and settles the payment. The successful JSON response
   includes the portable credential in the `twzrd_receipt` field:

```json
{
  "paid": true,
  "twzrd_receipt": {
    "preimage": {"schema": "twzrd.receipt.v6"},
    "leaf": "...",
    "signature": "..."
  }
}
```

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 status (2026-07-29): `npx agentcash@0.17.1 fetch ...` (and `@latest`
resolving to 0.17.1) completed a full paid-trust path against this host:
402 challenge → 0.05 USDC Solana settlement → `paid: true` body with valid V6
`twzrd_receipt` (offline + `POST /v1/receipts/verify`). Canary artifacts:
`ops-history/canaries/agentcash-s2-canary-20260729T2155Z/`. That run is
**INTERNAL_INTEROP** (payer `4LkEFj…` is on `INTERNAL_WALLETS`) — mechanical
CLI proof only, **not** organic external demand. Historical note: on 2026-06-23
the same client failed closed with `fee_payer_slot_already_signed`; that
incompatibility is superseded for 0.17.1. Sandboxed agents may still fail S2
by not executing shell commands — that is non-execution, not a dead CLI path.

## Step 4 — Use the credential

The signed receipt in the response JSON's `twzrd_receipt` field 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 | `POST /v1/intel/preflight` | None |
| Free | `POST /v1/receipts/verify` | None |
| Free | `GET /health` | None |
| Paid | `GET /v1/intel/trust/{pubkey}` | x402 USDC payment |
| Free | `GET /v1/intel/solana_market_*` | None |

## How x402 works

1. Client makes a normal HTTP request to a paid endpoint.
2. Server responds **402 Payment Required** with a `payment-required` header
   containing a base64-encoded x402 v2 PaymentRequired envelope.
3. Client chooses an entry from `accepts`, signs the Solana payment, and retries
   with `payment-signature` containing the x402 v2 PaymentPayload.
4. Server validates and settles the payment, processes the request, and returns
   a portable signed V6 receipt in the JSON `twzrd_receipt` field.

## Prices

| Resource | Price (USDC) |
|----------|-------------|
| Trust intel + signed receipt | 0.05 |
| Solana market data | 0.00 (free discovery) |
| 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.