# CashForge Evidence API — route coverage matrix

This public matrix is a compact QA companion to [`openapi-sample.yaml`](./openapi-sample.yaml). It describes the deployed contract without exposing access keys or private credentials.

| Route | Methods | Paid boundary | Success shape | Negative / edge cases | Reproducible check |
| --- | --- | --- | --- | --- | --- |
| `/api/read` | `POST`, `OPTIONS` | `access` query parameter; HTTP `402` when absent | `schema_version`, requested/final URL, status, SHA-256, bounded Markdown, latency, evidence boundary | Invalid JSON `400`; missing URL `400`; private/non-HTTPS URL or fetch failure `422`; redirect cap; output truncation | `curl -i -X POST "$BASE/api/read?access=REDACTED" -H 'content-type: application/json' -d '{"url":"https://example.com"}'` |
| `/api/brief` | `POST`, `OPTIONS` | `access` query parameter; HTTP `402` when absent | Tiered packet with `starter`, `monitoring`, or `premium` sources and retrieval metadata | Invalid JSON `400`; empty URL list `400`; one / three URL caps; previous SHA-256 change detection; per-source fetch errors | `curl -i -X POST "$BASE/api/brief?access=REDACTED&tier=monitoring" -H 'content-type: application/json' -d '{"urls":["https://example.com"],"previous_sha256":"..."}'` |
| `/api/base-pulse` | `GET`, `POST`, `OPTIONS` | `access` query parameter; HTTP `402` when absent | ETH/USD cross-source reference, spread, Base chain ID, block, gas, source statuses, caveats | Partial upstream failure returns `200` with `partial`; all upstreams unavailable returns `503`; invalid source data is isolated | `curl -i "$BASE/api/base-pulse?access=REDACTED"` |
| `/api/toku/webhook` | `GET`, `POST`, `OPTIONS` | None; intentionally no persistence | `{service,status,storage}` readiness response | Event bodies are not persisted or echoed; `OPTIONS` returns `204` | `curl -i "$BASE/api/toku/webhook"` and `curl -i -X POST "$BASE/api/toku/webhook" -d '{}'` |

## Acceptance gates

1. Every paid route returns `402` before the access boundary is satisfied.
2. No route accepts credentials in a target URL; private and local network targets are rejected.
3. Every successful evidence response includes retrieval time, source URL, status, hash or source metadata, and an explicit limitation boundary.
4. Every upstream dependency is isolated: one failed price source must not erase the other observations.
5. Webhook readiness never stores or echoes the event body.
6. The public sample contract and this matrix are documentation artifacts only; no access key is published.

## Delivery note

Use a read-only route inventory or sanitized export for a client-specific OpenAPI handoff. The public files demonstrate the contract shape; they are not a claim that any third-party production API has been tested.