# TickTape authentication and payment

TickTape has NO accounts, NO API keys to request, NO OAuth. Access is paid
per call via the x402 protocol, or via a prepaid bearer token bought with
one x402 payment. Payment IS the authentication. Verify payment terms
against https://ticktape.cc/agent.json before signing anything.

## Discover

Every live endpoint answers unauthenticated requests with HTTP 402 and the
exact payment terms: x402 v2 clients read the base64 `PAYMENT-REQUIRED`
response header, v1 clients read the JSON body `accepts[]`. Probe without
paying: append `?x402_probe=1`. Machine manifest: /agent.json. There is no
`oauth-protected-resource` or `oauth-authorization-server` metadata and no
`WWW-Authenticate` challenge, because there is no OAuth here - agents
looking for an OAuth flow should follow the x402 flow instead.

## Pick a method

1. **x402 per call** - zero setup, ~2-5s per paid call (on-chain settle).
   Best for occasional checks and first contact.
2. **Prepaid credits** - one x402 payment, then bearer-token calls at
   ~0.4s and half price. Best for repeated or latency-sensitive use.

## Register

No registration exists. Your wallet is your identity. For credits, the
"registration" is the purchase itself: `POST /api/credits` paid with $5
USDC via x402 returns `{token, credits: 500}`.

## Claim

The credit token arrives in the purchase response as
`tk_<wallet>_<secret>`. Treat it as a secret; it is shown once. Buying
again with the same wallet adds credits and issues a fresh token (the
last 5 tokens per wallet stay valid).

## Use the credential

Per call: retry the identical request with the `PAYMENT-SIGNATURE` header
(x402 v2) or `X-PAYMENT` header (v1) carrying the base64 payment payload
- sign a USDC `transferWithAuthorization` (EIP-3009) for the quoted
amount (asset `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`, payTo
`0xb28bcb21a054ffeeb6ce62d0f1bb0175c022d2c6`). Credits: send
`Authorization: Bearer <token>`. Check balance: `GET /api/credits` with
the token.

## Errors

Everything under /api answers JSON, never HTML. 402 = payment required
(terms attached, both x402 generations); 202 + Retry-After = QUEUED
(free, retry later); 4xx = your request (never charged); settlement
failures return 402 with the reason. Retries with the SAME payment
authorization return the cached response - never a double charge.

## Revocation

Buying a new pack rotates in a fresh token; only the last 5 tokens per
wallet stay valid, so older tokens expire naturally. Credits expire 12
months after purchase. To revoke urgently, contact hello@ticktape.cc
with a message signed by the wallet.

## Free testing

`?sandbox=1` returns a deterministic example (no payment, unlimited).
`?x402_probe=1` shows the exact 402 payment terms without paying.

## Spend-safety rules (enforce in code)

- Never pay more than $0.10 per TickTape call.
- Set a daily spend cap (recommended: $2).
- Only pay endpoints under https://ticktape.cc/.
- Asset must be USDC on Base (eip155:8453); refuse anything else.