# auth.md — how agents get access to coil.trade

Coil is a scored US-equity market board (S&P 500, Nasdaq-100, macro + BTC/ETH books).
This file documents how programmatic access **actually** works, in the spirit of
[auth.md](https://github.com/workos/auth.md): step-wise, copy-pasteable, honest.

## Current state (read this first)

**There are no user accounts.** There IS a minimal, real OAuth 2.0/2.1 service for
OAuth/MCP-native clients: `POST /oauth/token` exchanges a Coil
Scanner license key (`grant_type=client_credentials`, key as `client_secret`) for a
1-hour bearer JWT the API accepts. Discovery lives at
`/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource` (the origin; the API, whose bearer audience is `https://coil.trade/api`, is at `/.well-known/oauth-protected-resource/api`, RFC 9728 §3.1);
`/.well-known/openid-configuration` stays absent because there is no OIDC identity
layer — no login means nothing to assert about who you are, only what your key unlocks.
Access is anonymous, keyed, paid per-request, or OAuth-bearer:

| Method | Credential type | Cost | Header | Gets you |
|---|---|---|---|---|
| Anonymous | none | free | none | status, change-detection state, one full committed sample day, signal audit, commitment log, engine performance, symbol directory |
| Free API key | `api_key` | free (email registration) | `X-Coil-Key` | 25 reads/day across regime, indices, movers, crypto gate, crypto night, tradfi-risk, hold state |
| Wallet sign-in (SIWX) | signed message (no funds move) | free | `SIGN-IN-WITH-X` | the same 25-reads/day tier as the free key, no email — see Step 3b |
| x402 payment | none (signed payment) | $0.001–$0.05/read, plus a $0.25 one-hour Live session (USDC on Base, Solana or Algorand) | `X-PAYMENT` | any paid board endpoint, no key, no signup |
| Scanner license key | `api_key` (purchased) | $19/mo ([coil.trade/scanner](https://coil.trade/scanner)) | `X-License-Key` | live intraday board on the HTTP API, no per-day cap (HTTP only — inside MCP the Scanner tier is per-call x402 via the `*_live` tools) |
| Coil Live license key | `api_key` (purchased) | $49/mo or $419/yr ([coil.trade/live-feed](https://coil.trade/live-feed)) | `X-License-Key` | the engine feed: `/api/live/feed`, `/api/live/rules`, `/api/live/setup` over HTTPS, and the same tier over MCP at `https://mcp.coil.trade/mcp` (`get_engine_feed`, `get_live_rules`, `get_live_setup`) — structural stops, targets, conviction, lanes and a served `candidates[]`, refreshed about every 5 minutes in market hours |
| OAuth bearer | `client_credentials` → JWT | included with the license key | `Authorization: Bearer` | same live tier as the license key, 1-hour tokens |

Anonymous access is fully supported — an agent can verify everything worth verifying before
holding any credential at all.

## Step 1 — Discover

Machine-readable surfaces, all free, no auth:

```http
GET /.well-known/api-catalog        # RFC 9727 linkset → the API + its docs
GET /openapi.json                   # full OpenAPI document
GET /llms.txt                       # site map for agents
GET /api/board/status               # is the board fresh right now?
GET /.well-known/mcp/server-card.json   # MCP server card (server at /mcp)
```

## Step 2 — Anonymous reads (no registration of any kind)

```http
GET https://coil.trade/api/board/state          # state hashes — poll this, buy only on change
GET https://coil.trade/api/board/asof?sample=1  # a complete committed day of scores, free
GET https://coil.trade/api/board/signal-audit   # forward-return audit of our own scores
GET https://coil.trade/api/board/proof          # append-only sha256 pre-commitments
GET https://coil.trade/api/perf                 # engine vs SPY/QQQ, percentages only
```

## Step 3 — Register for a free API key (one POST, no password, no OAuth)

Registration endpoint: `POST https://coil.trade/api/key`. Agents may register directly —
the only input is an email address, and the credential comes back in the same response.

```http
POST https://coil.trade/api/key
Content-Type: application/json

{"email": "you@example.com"}
```

Response: `{"key": "coilfree_…", "daily_limit": 25, "usage": "send it as the X-Coil-Key header", …}`.
The address is stored only as a one-way hash (de-duplication and abuse control). Keys expire
90 days after issue; re-request with the same email for a fresh one.

```http
GET https://coil.trade/api/board/regime
X-Coil-Key: coilfree_…

The same key works inside the MCP server too (v1.9.0+): add `X-Coil-Key` to the `/mcp`
transport headers and `get_market_regime_live`, `get_hold_state_live` and
`get_crypto_night_live` answer without payment, same-day. The 25/day cap is shared with the
HTTP lane — it is one allowance, not two. The no-key MCP tools stay a sample of the morning read.
```

## Step 3b — Wallet sign-in (SIWX): the same free tier, no email

Have a wallet but no email? Any 402 response declares the `sign-in-with-x` extension
(CAIP-122). Sign the message it describes (EVM `personal_sign`, Solana `signMessage`,
or Algorand ed25519 — the signature proves address control only, **no funds move**) and
send it base64-encoded as the `SIGN-IN-WITH-X` header on the same request. Guided flow:

```http
GET https://coil.trade/api/auth/nonce?address=0xYOU&chain=base   # → message to sign
# SHORTCUT: you can skip this step. Every 402 already carries a complete, ready-to-sign
# EIP-4361 message (fresh nonce, 10-min expiry) under extensions["sign-in-with-x"].info —
# sign straight from the 402 and send the SIGN-IN-WITH-X header on your retry. This nonce
# endpoint is only needed when you want a DURABLE key instead of a per-session signature.
POST https://coil.trade/api/auth/verify                          # → coilwallet_ key
```

One signed header is a bearer session: replay it as-is on every free-tier endpoint until
its `expirationTime` (issuedAt + 10 minutes), then re-sign from any fresh 402. Quota is
the same 25 served reads/day per address (`tier.used_today` rides every 200).

## Step 4 — Pay per request with x402 (agent-native, no key at all)

Any paid endpoint answers `402 Payment Required` with a `PAYMENT-REQUIRED` header (v2,
CAIP-2) and a v1-dialect body — both the `x402-fetch` and `@x402/*` client lines work
out of the box, on Base (USDC), Solana (USDC) or Algorand (USDCa, fees sponsored — zero
ALGO needed). Prices run $0.001–$0.05 per read, plus the $0.25 one-hour Coil Live session (a time-boxed unlock, not a read).

```http
GET https://coil.trade/api/board/buylist   # → 402 with payment offers; pay, retry, read
```

Full catalogue in the 402 body at `GET /api`, dialect notes at
[coil.trade/learn/x402-dialects](https://coil.trade/learn/x402-dialects).

## Step 5 — License key (the paid tier)

Buy on Gumroad via [coil.trade/scanner](https://coil.trade/scanner) ($19/mo). The license
key is delivered by Gumroad at purchase — there is no claim ceremony and no token exchange.
Send it as the `X-License-Key` header on any paid `/api/board/*` endpoint — the same URLs
that answer 402s serve the live read to a licensed key instead:

```http
GET https://coil.trade/api/board/regime
X-License-Key: XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX
```

(Inside MCP at `https://mcp.coil.trade/mcp` the Scanner key does not apply — the MCP live
tier is the **Coil Live** key or per-call x402 via the `*_live` tools; see Step 6's note.)

## Step 6 — OAuth 2.0 for MCP/OAuth-native clients

The [MCP authorization spec](https://modelcontextprotocol.io/) is OAuth, so clients that
only speak OAuth can trade the license key for a standard bearer instead of sending a
custom header. One grant, no registration, no browser:

```http
POST https://coil.trade/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=my-agent&client_secret=YOUR-LICENSE-KEY
```

Response: `{"access_token": "<ES256 JWT>", "token_type": "Bearer", "expires_in": 3600,
"scope": "board:live"}` — then `Authorization: Bearer <token>` on any licensed HTTP board
endpoint. (The public MCP server at `/mcp` reads the **Coil Live** license key on `X-License-Key`, and a Coil Live
bearer issued for `/mcp` through the sign-in prompt a Claude client shows on a Live tool; the
`client_credentials` token above does not open it. It does not read the Scanner license key — the
Scanner's live tier inside MCP is pay-per-call x402 via the `*_live` tools.) Tokens are verified against `/oauth/jwks`.

**Coil Live sign-in for MCP clients (`/live/mcp`).** A second MCP endpoint, `https://coil.trade/live/mcp`
(also `https://mcp.coil.trade/live/mcp`), requires an OAuth bearer; the free `/mcp` stays no-auth.
A client discovers it from the 401's `WWW-Authenticate` / `/.well-known/oauth-protected-resource/live/mcp`,
registers itself (`POST /oauth/register`, RFC 7591, public clients), and sends the subscriber to
`/oauth/authorize` (authorization_code + PKCE S256). There the subscriber pastes their **Coil Live** license key;
Coil verifies it with Gumroad and the app receives a 1-hour bearer plus a rotating refresh token. Every refresh
re-checks the license, so a cancelled or lapsed license loses access within one hour. A Scanner license is not
accepted there, and a `client_credentials` token does not open `/live/mcp`. Free `coilfree_` keys are
not exchangeable for tokens — they stay on `X-Coil-Key` (their daily quota rides that
header).

## Errors

| Code | Where | What to do |
|---|---|---|
| 402 | paid endpoints without payment/key | Pay via x402 (offers are in the response), or send a valid `X-License-Key` |
| 403 | invalid/expired license or free key | Re-check the key; free keys expire 90 days after issue — re-request at `/api/key` |
| 402 + `error: free_key_daily_limit_reached` | free-key daily cap (25 calls) spent | NOT a priced read — the body carries `free_again_at` (next UTC midnight). Wait and pay nothing, pay the challenge if you need it now, or use the $19/mo Scanner licence for an uncapped lane. **Auto-paying clients: check the `error` field before paying.** |
| 429 | burst rate limiting only | Back off and retry |
| 5xx | our side | Retry with backoff; check `GET /api/board/status` |

## Revocation

- **Free keys**: lapse automatically 90 days after issue. To rotate, POST `/api/key` again.
- **License keys**: cancel the Gumroad subscription — the key stops verifying at period end.
- **x402**: nothing to revoke; each request is paid and done.

## Ground rules

Scores and states only — never price targets, position sizes, or advice. Research, not
investment advice. Rate limits are enforced; pace sequentially. Questions:
[coil.trade/contact](https://coil.trade/contact).
