# auth.md

Agent registration and authentication for the Node Scorecard API.

## Audience

This document is for autonomous AI agents and their developers. Human users do not need it: the free documentation endpoints require nothing at all.

## Registration

**No registration is required, and no registration endpoint exists.** There is no sign-up, no account, no API key, no OAuth client, no bearer token and no OAuth authorization server. An agent does not need to be provisioned before its first call.

Provisioning happens inline, per request, through payment. The resource itself is the provisioning endpoint: call it, and the `402` response tells you exactly how to become authorised for that call.

## Supported authentication methods

| Method | Identity | Credential | Where |
|---|---|---|---|
| x402 payment | Anonymous. The paying wallet address is the only identity, and it is never registered or stored as an account. | A signed payment authorisation produced by the agent wallet. | `PAYMENT` request header |
| None | Anonymous | None | Free endpoints |

Scheme: `exact` on network `eip155:8453` (Base mainnet). Signatures follow the x402 v2 specification.

## Credential use

1. Send a plain `GET` to any paid endpoint. You receive `402 Payment Required` with a `PAYMENT-REQUIRED` response header containing base64-encoded JSON.
2. Decode it. It carries `payTo`, `network`, `amount`, `asset` and `maxTimeoutSeconds`.
3. Sign the payment with your own wallet. The credential is produced by the agent, not issued by this service, so there is nothing to claim and nothing to revoke.
4. Retry the identical request with the `PAYMENT` header. On settlement the response body is returned.

Each credential authorises exactly one request. It expires with `maxTimeoutSeconds` and cannot be reused. There is no session, no refresh, and no long-lived token to protect.

## Facts

- Base mainnet `eip155:8453` — USDC `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` -> `0x0fcc5724d2dddf79ce1af1f091a823fd6438ef73`
- Solana mainnet `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` — USDC `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` -> `7KjmSaLhpJJScHEdmUV2CDR47FVxR7jv7DV8QEMszhDi` (transaction fee sponsored by the facilitator: no SOL needed)
- Facilitator: https://facilitator.payai.network
- Requests returning HTTP >= 400 are never settled. Errors are not charged.

## Machine-readable discovery

- `https://nodescorecard.xyz/manifest` service manifest
- `https://nodescorecard.xyz/openapi.json` OpenAPI 3.1 description
- `https://nodescorecard.xyz/.well-known/api-catalog` RFC 9727 catalog
- `https://nodescorecard.xyz/llms.txt` plain-text summary