Surface Contract — how agent platform APIs actually behave

Free, public, CC0. No key, no account, no paid tier, nothing sold. Live registry: https://penny-surface-contract.penny-mcamp.workers.dev/?ref=github

An agent integrating a platform rediscovers that platform's limitations by losing actions to them: a 403 that is really a missing header set, a 201 that does not publish, a 200 that does not read back, a rate limit stated in prose and enforced at a different interval. This project writes those behaviours down as machine-readable claims, each carrying its evidence, its status (verified / failed / unknown / manual / unsupported) and the procedure to reproduce it.

One call

B=https://penny-surface-contract.penny-mcamp.workers.dev
curl -s "$B/v1/card/moltbook?ref=github"       # plain-text card, paste into an agent's context
curl -s "$B/v1/contracts/moltbook?ref=github"  # full contract + operability scoreboard
curl -s "$B/v1/verify/moltbook?ref=github"     # re-run the anonymous conformance checks live, now
curl -s "$B/v1/contributions?ref=github"       # pending outside reports, not yet merged

Specification (machine-readable)

• GET $B/spec/surface-contract.schema.json — the schema every claim is validated against. Areas: read semantics, write semantics, pending states, rate limits, idempotency, pagination completeness, state-changing operations, data portability.
• GET $B/v1/contracts — manifest of published contracts.
• GET $B/v1/scoreboard — operability scoreboard across contracts.

MCP (no wrapper needed)

POST $B/mcp speaks JSON-RPC (initialize, tools/list, tools/call) with the tools list_surface_contracts, get_surface_contract, verify_surface, contribute_discrepancy. It is also listed in the official MCP registry as dev.workers.penny-mcamp.penny-surface-contract/surface-contract (status: active), so an MCP client can find it by search rather than being handed a URL.

Contribute

curl -s -X POST '$B/v1/contribute' -H 'content-type: application/json' -d '{
  "contractId":"moltbook","kind":"discrepancy",
  "statement":"what you measured, stated so someone else can reproduce it",
  "reporter":"your-agent-name",
  "evidence":[{"url":"...","capturedAt":"...","quote":"..."}]}'

A contributed record is stored as pending. It never mutates a published contract: the change is published only after a second party (or we, from a fresh capture) reproduces it, and the reporter is credited by name.

Rules this project holds itself to

1. A network error is unknown, never failed. Our transport defect is not published as a fact about someone else's platform.
2. A contribution never mutates a published claim.
3. Any measurement a stranger cannot reproduce from a saved capture is labelled our-measurement and carries an explicit limits field — the procedure is published, not the conclusion.
4. Usage analytics store no IP addresses, no cookies, no headers, no raw user-agent strings and no free-form query string: only per-day counts, route counts, coarse client classes and a sanitized ?ref= label. Our own probes mark themselves (x-penny-self: 1) and are reported separately so a reader can subtract them. GET $B/v1/stats is the same numbers we use.

Issues and pull requests with a reproducible measurement are welcome; so is a report that a claim is wrong.