# auth.md - TruthFoundry API access

TruthFoundry is a **read-only news intelligence API** with Ed25519 provenance on
every synthesized brief and article receipt. The web record is free to read;
every `/v1/*` call and MCP tool needs a credential.

## Credential types

1. **Bearer API key** (`nwb_...`). Present it on every request as
   `X-Newsboy-Key: <key>` or `Authorization: Bearer <key>`.
2. **x402 pay-per-call** (no key, no account). Any `/v1` GET without a key
   returns **HTTP 402** with x402 payment terms (USDC on Base). Retry with the
   payment attached and the call executes. Ideal for agents.
3. **The free agent lane** (no key, no payment). `GET https://truthfoundry.ai/v1/factcheck?instruments=1&q=...` answers keyless: the deterministic record readout with receipts, per-IP rate limited.

## Agent registration

1. **Free tier** - `POST https://truthfoundry.ai/billing/signup` with body
   `{"email":"you@example.com"}` returns `{"key":"nwb_..."}` (100 req/day,
   shown exactly once - store it; the email is a contact label, not a recovery path).
2. **Paid plans** - live prices and quotas at `GET https://truthfoundry.ai/pricing.json` (the one canonical machine
   source; human page at https://truthfoundry.ai/pricing). Checkout runs through the DRM3 account portal; the key is claimed once at `/welcome` after payment.
3. **Metering** - check usage any time: `GET https://truthfoundry.ai/v1/usage` with your key.
4. **Revocation** - keys are revoked on request (support@drm3.io) or on abuse. Paid keys follow the subscription (past_due / canceled -> revoked).

## Discovery

- OpenAPI: https://truthfoundry.ai/openapi.json
- Agent skills index: https://truthfoundry.ai/.well-known/agent-skills/index.json
- MCP server card: https://truthfoundry.ai/.well-known/mcp/server-card.json (live endpoint: https://truthfoundry.ai/mcp)
- API catalog (RFC 9727): https://truthfoundry.ai/.well-known/api-catalog
- Protected-resource metadata (RFC 9728): https://truthfoundry.ai/.well-known/oauth-protected-resource
- Signing keys: https://truthfoundry.ai/.well-known/truth-foundry-keys.json
- Prices + quotas (canonical JSON): https://truthfoundry.ai/pricing.json | Security contact: https://truthfoundry.ai/.well-known/security.txt
- Plain-text overview for LLMs: https://truthfoundry.ai/llms.txt