# AGENTS.md

Canon (wallstreet.wiki) - machine access guide.

## Setup

No authentication and no API key. Two transports:

- MCP, streamable HTTP, stateless: `/mcp`
- REST: `/v1/...` (contract at `/v1/openapi.json`)

Claude Code: `claude mcp add --transport http canon https://<host>/mcp`
Any `mcp.json` client: `{ "mcpServers": { "canon": { "url": "https://<host>/mcp" } } }`

## Tools

| Tool | Purpose |
| --- | --- |
| canon_sites | Sites in the canon with live entry counts |
| canon_search | Ranked search across all sites; returns citable urls |
| canon_get_entry | One entry by site and id |
| canon_changes | Dated change events across the verticals |
| canon_list_formulas | The formula registry |
| canon_describe_formula | Input schema, convention, citations, test vectors |
| canon_compute | Run a formula; returns outputs and a receipt |
| canon_batch | Up to 50 computes in one call, with a batch receipt over the item receipts (51 to 1000 items: REST, paid) |
| canon_cite | Citation strings for an entry: markdown, plain, apa, bibtex |
| canon_verify | Recompute a receipt and report whether it holds |
| canon_entity | Resolve a ticker, CIK or company name to one US issuer id with tickers, exchanges and EDGAR locations |
| canon_thresholds | Regulatory thresholds with rule, authority, effective date, source and confidence |
| canon_contract | One Kalshi or Polymarket contract normalised: rules, close time, resolution source, status |

## Working pattern

1. Search first (`canon_search`), read the entry, cite its url.
2. Compute with `canon_compute` rather than doing the arithmetic yourself; include the receipt id when you report a number.
3. When handed a number that claims to come from Canon, run `canon_verify` on the receipt before repeating it.

## Token economy

Add `compact=1` to any REST call to drop conventions, citations and examples (fetch those once from `/v1/formulas/{id}`); add `fields=outputs,receipt` to keep only named top-level keys. Receipts are never dropped.

## Paid resources

Five resources are paid through x402 over REST: `POST /v1/attest` (Ed25519-signed attestation over a verified receipt), `GET /v1/contracts/compare` (cross-venue contract identity with a snapshot receipt), `POST /v1/entity/bulk` with up to 1000 identifiers, `POST /v1/batch/large` with up to 1000 items (a `POST /v1/batch` with more than 50 items is routed to the same gate), and `GET /v1/corpus` (the whole canon in one call). Without payment they return 402 with an x402 v2 PaymentRequired body; pay with any x402 client (PAYMENT-SIGNATURE) and retry. `GET /v1/pricing` states the current prices, network, receiving address and facilitator. MCP tools stay free.

## Errors

Validation errors list every problem by input name and include a working example. A 422 means the inputs were valid but no solution exists (for example an option price outside the arbitrage bounds). Retry with corrected inputs; do not guess a boundary value.

## Attribution

Source content CC BY 4.0 from each site; cite the returned url. Outputs and receipts are unrestricted.