# ZERO Public Operator Contracts

These public read-only contracts expose verified autonomous behavior for agents,
operators, dashboards, and launch surfaces. They are public by design and do not
expose secrets, private keys, raw operator tokens, or mutation capabilities.

Base URL: `https://getzero.dev`

## Endpoints

| Endpoint | Schema | Purpose |
| --- | --- | --- |
| `GET /api/public/operators` | `zero.public_operators.v1` | Discover all public ZERO operators. |
| `GET /api/public/operators/foundation` | `zero.public_operator.v1` | Fetch a normalized public operator profile. |
| `GET /api/foundation/live-certification-readiness` | `zero.foundation_live_certification_readiness.v1` | Inspect Foundation owner-drill readiness, blockers, and testnet submit/cancel promotion state. |
| `GET /api/foundation/operator-control-readiness` | `zero.foundation_operator_control_readiness.v1` | Inspect Foundation Take Over readiness, missing proof blockers, and Sentinel transcript publish state. |
| `GET /api/ops/journal-finality` | `zero.journal_finality_ops.v1` | Inspect the remaining journal public-chain finality blocker, recommended public-chain finalizer profile, and score-promotion gate. |
| `GET /api/replays` | `zero.replay_index.v1` | Discover public DECISION_LOOP replay summaries. |
| `GET /api/replays/entrypoints` | `zero.replay_entrypoints.v1` | Discover the public replay graph across homepage, operator profile, agent profile, replay index, detail, export capsule, and share-image entrypoints. |
| `GET /api/replays/foundation-genesis` | `zero.decision_replay.v1` | Fetch a DECISION_LOOP replay payload. |
| `GET /api/replays/foundation-genesis/receipt-card` | `zero.decision_receipt_card.v1` | Fetch a public-safe shareable decision receipt card with replay, JSON, export, share-image, operator, and graph links, without private traces or performance metrics. |
| `GET /api/replays/decision-artifacts` | `zero.public_decision_artifacts.v1` | Fetch recurring public decision artifact shelves that roll receipt cards and graph-context links across refusal, followthrough, and same-policy families. |
| `GET /api/replays/foundation-genesis/graph-context` | `zero.replay_graph_context.v1` | Fetch retained public replay adjacency and hash coverage without raw prompts, private traces, operator ids, private keys, or performance metrics. |
| `GET /api/replays/decision-graph` | `zero.replay_decision_graph.v1` | Fetch the public-safe multi-replay decision graph across retained refusal, followthrough, same-source, and same-policy replay families. |
| `GET /api/arena` | `zero arena payload` | Fetch current public operator arena entry. |
| `GET /api/arena/rewards` | `zero weekly rewards payload` | Fetch current proof-based rewards. |
| `GET /api/seasons` | `zero season payload` | Fetch proof-based season leaderboard state. |
| `GET /api/coliseum` | `zero.coliseum.paper_bracket.v0` | Fetch the current replay-backed paper tournament bracket. |
| `GET /api/coliseum/history` | `zero.coliseum.league_retention.v0` | Fetch the provenance-backed retained weekly paper bracket history gate for League promotion evidence; paper-only, no execution, no performance claims. |
| `GET /api/registry` | `zero.registry.catalog.v0` | Fetch the signal-only ZERO Registry catalog. |
| `GET /api/registry/reputation` | `zero.registry.reputation.v0` | Fetch supplier and listing reputation for the read-only Registry. |
| `GET /api/runtime?q=product` | `zero.engine_product_truth.v1` | Fetch the operator-facing Hyperliquid Runtime product truth contract: setups, refusals, immune state, execution quality, MCP, and deploy boundaries. |
| `GET /api/runtime?q=proof` | `zero.engine.proof.v1` | Fetch the read-only Runtime proof contract for live canary, immune system, circuit breaker, refusal, near-miss, and execution-quality evidence surfaces. |
| `GET /api/runtime?q=evidence-depth` | `zero.engine.evidence_depth.v1` | Fetch the retained live-Runtime evidence-depth contract and current sample gaps. |
| `GET /api/runtime?q=immune`, `circuit-breaker`, `rejections`, `near-misses`, `execution-quality` | `zero.engine.native_dimension_readback.v1` | Fetch native app-owned public readbacks for the operator-facing Runtime dimensions without upstream fallback or runtime mutation. |
| `GET /api/ops/engine-evidence-cadence` | `zero.engine.retained_evidence_cadence.v1` | Fetch the read-only retained Runtime evidence cadence monitor. |
| `GET /api/ops/engine-evidence-cadence/history` | `zero.engine.retained_evidence_cadence_history.v1` | Fetch retained cadence history for private reliability calibration. |
| `GET /proofs/engine-retained-evidence.harvest.json` | `zero.engine.retained_evidence.v1` | Fetch the generated public-safe retained Runtime evidence harvest. |
| `GET /proofs/engine-evidence-cadence-history.harvest.json` | `zero.engine.retained_evidence_cadence_history_artifact.v1` | Fetch retained cadence workflow samples without runtime mutation. |
| `GET /api/growth/multi-operator-history` | `zero.growth_multi_operator_history.v1` | Fetch aggregate-only distinct-operator receipt history without exposing operator ids or metadata. |
| `GET /api/deployments/hosted-operator-launch-receipt` | `zero.hosted_operator_launch_receipt.v1` | Fetch the replay-linked hosted operator launch receipt and freshness gate. |
| `POST /oss/mcp tools/list` | `zero.mcp.tools.v1` | Discover read-only public tools, including evaluate, heat, approaching, pulse, regime, brief, immune, diagnostics, rejections, near-misses, and execution-quality. |
| `POST /oss/mcp tools/call` | `zero.mcp.public_tool_results.v1` / public schemas | Call public read-only proof and engine tools. Live-action tools return `zero.mcp.refusal.v1`. |

## Schema Artifacts

| Artifact | Purpose |
| --- | --- |
| `/contracts/zero.public_operators.v1.schema.json` | JSON Schema for the public operator index. |
| `/contracts/zero.public_operator.v1.schema.json` | JSON Schema for a normalized public operator profile. |
| `/contracts/zero.decision_replay.v1.schema.json` | JSON Schema for DECISION_LOOP replay payloads. |
| `/contracts/zero.decision_receipt_card.v1.schema.json` | JSON Schema for public-safe shareable decision receipt cards. |
| `/contracts/zero.public_decision_artifacts.v1.schema.json` | JSON Schema for recurring public decision artifact shelves. |
| `/contracts/zero.replay_entrypoints.v1.schema.json` | JSON Schema for public replay entrypoint graph coverage. |
| `/contracts/zero.replay_graph_context.v1.schema.json` | JSON Schema for retained public replay graph context and hash coverage. |
| `/contracts/zero.replay_decision_graph.v1.schema.json` | JSON Schema for multi-replay decision graph depth. |
| `/contracts/zero.coliseum.paper_bracket.v0.schema.json` | JSON Schema for the public Coliseum paper bracket. |
| `/contracts/zero.coliseum.league_retention.v0.schema.json` | JSON Schema for the public Coliseum League retention gate. |
| `/contracts/zero.registry.catalog.v0.schema.json` | JSON Schema for the public ZERO Registry catalog. |
| `/contracts/zero.registry.reputation.v0.schema.json` | JSON Schema for Registry supplier/listing reputation. |
| `/contracts/zero.engine_product_truth.v1.schema.json` | JSON Schema for the public Hyperliquid Runtime product truth contract. |
| `/contracts/zero.engine.proof.v1.schema.json` | JSON Schema for the Runtime proof contract. |
| `/contracts/zero.engine.evidence_depth.v1.schema.json` | JSON Schema for retained live-Runtime evidence depth and sample gaps. |
| `/contracts/zero.engine.native_dimension_readback.v1.schema.json` | JSON Schema for native read-only Runtime dimension readbacks. |
| `/contracts/zero.growth_multi_operator_history.v1.schema.json` | JSON Schema for aggregate-only multi-operator growth history. |
| `/contracts/zero.hosted_operator_launch_receipt.v1.schema.json` | JSON Schema for the hosted operator launch receipt. |
| `/contracts/decision-replay.examples.json` | Schema-validated replay examples for agent ingestion. |
| `/contracts/zero.mcp.tools.v1.schema.json` | JSON Schema for public OSS MCP tool discovery. |
| `/contracts/zero.mcp.refusal.v1.schema.json` | JSON Schema for structured public OSS MCP mutation refusal. |
| `/contracts/zero.mcp.public_tool_results.v1.schema.json` | JSON Schema for simple public OSS MCP tool results. |
| `/contracts/public-operator.openapi.yaml` | OpenAPI contract for public proof endpoints. |
| `/contracts/public-operator.examples.json` | Schema-validated example payloads for agent ingestion and fixtures. |

## MCP Tools

Use `POST /oss/mcp` with JSON-RPC 2.0 `tools/call` for public read-only
agent discovery. The authenticated `/mcp` endpoint exposes the same public
proof tools alongside scoped operator tools.

| Tool | Auth | Purpose |
| --- | --- | --- |
| `zero_list_public_operators` | none | Returns `GET /api/public/operators`. |
| `zero_get_public_operator` | none | Returns `GET /api/public/operators/foundation`. |
| `zero_get_arena` | none | Returns arena data; includes rewards by default. |
| `zero_get_season` | none | Returns `GET /api/seasons`. |

## Discovery Flow For Agents

1. Read `https://getzero.dev/.well-known/zero.json`.
2. Validate it with `https://getzero.dev/contracts/zero.discovery.v1.schema.json`.
3. Read `https://getzero.dev/llms.txt`.
4. Fetch `https://getzero.dev/contracts/public-operator.openapi.yaml`.
5. Fetch `https://getzero.dev/contracts/zero.mcp.tools.v1.schema.json`.
6. Fetch `https://getzero.dev/contracts/zero.mcp.refusal.v1.schema.json`.
7. Fetch `https://getzero.dev/contracts/zero.mcp.public_tool_results.v1.schema.json`.
8. Fetch `https://getzero.dev/contracts/zero.public_operators.v1.schema.json`.
9. Fetch `https://getzero.dev/contracts/zero.public_operator.v1.schema.json`.
10. Fetch `https://getzero.dev/contracts/zero.decision_replay.v1.schema.json`.
11. Fetch `https://getzero.dev/contracts/zero.decision_receipt_card.v1.schema.json`.
12. Fetch `https://getzero.dev/contracts/zero.replay_graph_context.v1.schema.json`.
13. Fetch `https://getzero.dev/api/public/operators`.
14. Validate the index against `zero.public_operators.v1`.
15. Follow `operators[0].public_operator_url` for profile detail.
16. Validate the profile against `zero.public_operator.v1`.
17. Follow `profile.evidence.live_certification_readiness.href` for live-certification readiness, `profile.evidence.live_certification_readiness.proof_blockers`, `profile.evidence.live_certification_readiness.next_blocker`, `profile.evidence.live_certification_readiness.owner_action.checklist`, `profile.evidence.live_certification_readiness.owner_action.testnet_approval_packet`, `profile.evidence.live_certification_readiness.owner_action.approval_handoff`, `profile.evidence.live_certification_readiness.owner_action.post_approval_retry`, `profile.evidence.live_certification_readiness.drill_gate.server_submit_enabled`, and `profile.evidence.live_certification_readiness.testnet_drill.promotion_eligible` before treating an owner drill as promoted.
18. Follow `profile.evidence.operator_control_readiness.href` for Take Over readiness, `profile.evidence.operator_control_readiness.proof_blockers`, `profile.evidence.operator_control_readiness.next_blocker`, `profile.evidence.operator_control_readiness.owner_actions`, and `profile.evidence.operator_control_readiness.proof_chain.ordered_steps` before treating Sentinel operator-control proof as complete.
19. Follow `profile.evidence.operator_control_readiness.journal_finality_ops` or fetch `https://getzero.dev/api/ops/journal-finality` before treating the final Q1 score blocker as cleared.
20. Fetch `https://getzero.dev/api/replays`.
21. Fetch `https://getzero.dev/api/replays/foundation-genesis`.
22. Validate the replay against `zero.decision_replay.v1`.
23. Fetch `https://getzero.dev/api/replays/foundation-genesis/receipt-card`.
24. Validate the receipt card against `zero.decision_receipt_card.v1`.
25. Fetch `https://getzero.dev/api/replays/foundation-genesis/graph-context`.
26. Validate retained graph context against `zero.replay_graph_context.v1`.
27. Fetch `https://getzero.dev/api/replays/decision-graph`.
28. Validate decision graph depth against `zero.replay_decision_graph.v1`.
29. Fetch `https://getzero.dev/api/coliseum`.
30. Validate the bracket against `zero.coliseum.paper_bracket.v0`.
31. Fetch `https://getzero.dev/api/coliseum/history`.
32. Validate the retained League gate against `zero.coliseum.league_retention.v0`, require every sample to include paper-only provenance, and require `score_gate.state === "retention_ready"` before treating retained weekly League proof as score-moving.
33. Fetch `https://getzero.dev/api/registry`.
34. Validate the Registry catalog against `zero.registry.catalog.v0`.
35. Fetch `https://getzero.dev/api/registry/reputation`.
36. Validate reputation against `zero.registry.reputation.v0`.
37. Fetch `https://getzero.dev/api/runtime?q=product`.
38. Validate the Runtime product truth contract against `zero.engine_product_truth.v1`.
39. Fetch `https://getzero.dev/api/runtime?q=proof`.
40. Validate the Runtime proof contract against `zero.engine.proof.v1`.
41. Fetch `https://getzero.dev/api/runtime?q=evidence-depth`.
42. Validate the evidence-depth contract against `zero.engine.evidence_depth.v1`.
43. Fetch `https://getzero.dev/api/ops/engine-evidence-cadence`.
44. Confirm the retained Runtime evidence cadence is read-only and active.
45. Fetch `https://getzero.dev/api/ops/engine-evidence-cadence/history`.
46. Confirm cadence history stays read-only, has retained samples, and keeps public numeric Operator Scores disabled.
45. Fetch `https://getzero.dev/proofs/engine-retained-evidence.harvest.json` and confirm the harvest is public-safe and non-mutating.
46. Validate `/oss/mcp` `tools/list` includes read-only engine tools for evaluate, heat, approaching, pulse, regime, brief, immune, diagnostics, rejections, near-misses, and execution-quality.
47. Call `/oss/mcp` schema-backed engine tools for product, proof, evidence depth, cadence, and native route readbacks.
48. Confirm `/oss/mcp` refuses live-action probes such as order placement with `zero.mcp.refusal.v1`.
49. Fetch `https://getzero.dev/api/deployments/hosted-operator-launch-receipt`.
50. Validate the launch receipt against `zero.hosted_operator_launch_receipt.v1` and fail stale receipts after `expires_at`.
51. Use `zero_get_arena` and `zero_get_season` when MCP is available.

## Verification

Public proof contracts are schema-validated in CI. The public OSS MCP endpoint is
checked by a scheduled GitHub workflow named `OSS MCP Smoke`, which verifies
tool discovery, read-only annotations, public proof calls, and structured
mutation refusal against `https://getzero.dev`.

## Safety Boundary

These contracts are read-only. They cannot execute orders, start sessions,
approve Hyperliquid agents, sign actions, reveal private keys, or mutate runtime
state. Live execution remains behind explicit operator authorization and runtime
safety gates.