Discovery & meta routes

Eight unauthenticated, free routes that expose how the API works to humans, agents, crawlers, and payment facilitators. Use them to bootstrap an integration without ever holding a key, and to verify connectivity before paying for data routes.

Routes

GET /health

Liveness + DB reachability check. Returns { status: 'ok' } when the FastAPI process and the Supabase pooler are both reachable; returns 503 when the DB ping fails. Railway's auto-restart policy keys off this — don't rely on it for SLO measurement, but it's a safe smoke-test.

GET /openapi.json

Machine-readable OpenAPI 3.1 spec for every public route. Generated by FastAPI from the route signatures and Pydantic models. Use it to scaffold a typed client (openapi-typescript, openapi-python-client, etc.) — the spec stays in sync with the running service automatically.

GET /skill.md

Agent skill definition — a markdown summary of what the API does, base URL, pricing, and capability surface. Modeled on transit402.dev/skill.md. Drop into an LLM context window and the agent can drive the API without further onboarding.

GET /llms.txt

Plain-text LLM-context summary per llmstxt.org. Smaller than skill.md, optimized for crawlers building structured indexes of agent-callable APIs.

GET /prompts.json

Example agent prompts mapped to endpoint sequences. Each entry pairs a user-facing prompt ("find the cheapest oat milk near me") with the exact API calls that satisfy it. Useful for prompt-engineering workshops and eval suites.

GET /.well-known/x402

x402 v2 payment discovery — wallet address, supported scheme, network (Base USDC), facilitator URL. AgentCash and any x402-aware HTTP client read this on first contact to know how to pay.

GET /.well-known/mpp

Tempo MPP payment discovery — alternative micropayment scheme. Same payload shape as the x402 one, different protocol. Reserved for a future Tempo USDC settlement path; currently a stub that lists the wallet.

GET /methodology.md

Full institutional-grade methodology doc for the published indices — aggregation formulas, regional rollups, sanity bounds, beta-vs-live policy, BLS / USDA / FAO citations. Hosted as a static markdown read so hedge-fund analysts and journalists can fetch it without authentication. Mirrored at /docs/methodology.

Bootstrapping an integration

The recommended onboarding sequence for an agent or new client:

1. Read /skill.md or /llms.txt to learn what the API does.
2. Read /.well-known/x402 to learn how to pay for data routes.
3. Pull /openapi.json if you want a typed client. Discovery routes (/v1/stores, /v1/chains) are free — start there to confirm the shape.
4. Hit /health before paid calls in production to confirm the service is reachable.

Sample payloads

/health (200 OK)

{ "status": "ok" }

/health (503 — DB unreachable)

HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{ "detail": "db unreachable" }

/skill.md (excerpt)

# MainMarket — Grocery Shelf Intelligence

You can call the MainMarket API to get real-time US grocery prices, store
locations, coupons, and published inflation indices.

Base URL: https://api.mainmarket.com
Pricing: discovery routes are free; data routes are $0.01 per call via x402.

## Capabilities
- /v1/stores            — geo-search 70+ chain stores
- /v1/products          — canonical product catalog (528k SKUs)
- /v1/prices            — store-scoped pricing with tiered fallback
- /v1/coupons           — active coupons with savings math
- /v1/indices/{slug}    — published price indices (egg, soda, baskets)

See https://api.mainmarket.com/openapi.json for the machine-readable spec.

/.well-known/x402 (excerpt)

{
  "version": "2",
  "supported_schemes": ["exact"],
  "supported_networks": ["base"],
  "asset": {
    "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "symbol": "USDC",
    "decimals": 6
  },
  "facilitator": "https://x402.coinbase.com/api",
  "facilitator_display_name": "Coinbase x402",
  "pay_to": "0x...",
  "discovery": "https://x402scan.com/?host=api.mainmarket.com"
}

Caching

• /health: no cache (must reflect live state).
• All other static routes: Cache-Control: public, max-age=3600 (1 hour). Files are checked into the repo and only change on deploys.
• /openapi.json: Cache-Control: public, max-age=300 (5 minutes) so a fresh deploy propagates within minutes to clients that re-fetch periodically.

Errors

These routes don't have validation — a request either matches the path or 404s. The only meaningful error is 503 on /health when the DB ping fails (used by Railway's auto-restart).