# Headless Oracle

> Proposed reference implementation of environment.market_state — open as PR #9 on Mastercard's Verifiable Intent repo and filed as an IETF I-D for the environment.* family.
> Ed25519-signed market-state attestations for 28 global exchanges. 60-second TTL. Fail-closed.
> MCP server + REST API + x402 micropayments.

Execution-environment verification for autonomous financial agents. At Layer 3 of a Verifiable Intent mandate, an agent holding a valid L2 credential still needs cryptographic proof that the market it is about to execute into is actually open. Amount validation at L2 is not evidence of market state at L3. Headless Oracle provides that evidence as a signed receipt.

The environment.* constraint family is a sibling-type namespace: environment.market_state covers exchange-session state, and environment.wallet_state covers on-chain payment-source state. Both specs share the same fail-closed posture, JWKS caching discipline, cross-spec composition semantics, and family-wide register conventions — the result of coordinated drafting across sibling reference implementations rather than isolated per-type work.

Model-agnostic infrastructure. Works with any AI agent regardless of model tier — from GPT-5 nano to frontier reasoning models like Anthropic Mythos. Receipts are the same $0.05/MTok agents and $125/MTok agents both consume.

Regulatory alignment: Provides cryptographic venue-state attestation consistent with emerging regulatory direction on tokenized collateral and digital-asset derivatives (CFTC Staff Letter 25-39, Dec 2025; SEC Project Blueprint on Tokenized Collateral, Nov 2025). Final CFTC rulemaking expected Aug 2026.

Agents can pay for access autonomously via x402 protocol (USDC on Base mainnet) — no human API key provisioning required.

Headless Oracle returns cryptographically signed receipts confirming whether an exchange is OPEN, CLOSED, HALTED, or UNKNOWN. Every receipt includes an Ed25519 signature with a 60-second TTL. UNKNOWN must be treated as CLOSED (fail-closed). Used as a pre-trade verification gate by autonomous trading agents.

- [Full Documentation](https://headlessoracle.com/llms-full.txt): Complete API reference, schemas, and integration guides in one file.

## MCP Tools

- [get_market_status](https://headlessoracle.com/mcp): Check if an exchange is open with signed Ed25519 receipt
- [get_market_schedule](https://headlessoracle.com/mcp): Next open/close times, holidays, lunch breaks
- [list_exchanges](https://headlessoracle.com/mcp): All 28 supported exchanges with MIC codes

## API Endpoints

- [GET /v5/status](https://headlessoracle.com/docs): Signed market-state receipt (auth required)
- [GET /v5/batch](https://headlessoracle.com/docs): Multi-exchange batch check (auth required)
- [GET /v5/briefing](https://headlessoracle.com/docs): Daily market intelligence summary
- [GET /v5/demo](https://headlessoracle.com/docs): Free signed demo receipt (no auth)
- [GET /v5/schedule](https://headlessoracle.com/docs): Next open/close times with lunch breaks
- [GET /v5/exchanges](https://headlessoracle.com/docs): All 28 supported exchanges directory
- [GET /v5/health](https://headlessoracle.com/docs): Signed liveness probe

## Integration

- [MCP Setup](https://headlessoracle.com/docs/quickstart): npx headless-oracle-mcp for Claude Desktop, Cursor, Windsurf
- [Python SDK](https://pypi.org/project/headless-oracle/): pip install headless-oracle
- [JavaScript SDK](https://www.npmjs.com/package/@headlessoracle/verify): npm install @headlessoracle/verify
- [Go SDK](https://github.com/LembaGang/headless-oracle-go): go get github.com/LembaGang/headless-oracle-go
- [LangChain](https://pypi.org/project/headless-oracle-langchain/): headless-oracle-langchain tool
- [CrewAI](https://headlessoracle.com/docs/integrations/crewai): MCPServerStdio configuration
- [x402 Payment](https://headlessoracle.com/docs/integrations/x402): Pay-per-call $0.001 USDC on Base

## Pre-Trade Verification Pattern

- [Pattern Specification v2.0](https://headlessoracle.com/docs/specifications/pre-trade-stack): Composable deployment pattern for autonomous trading agents. Step 1 (execution-environment verification) is normatively specified by `environment.market_state` + `environment.wallet_state` in the Verifiable Intent environment.* family.
- [Machine-Readable Pattern](https://headlessoracle.com/v5/pre-trade-stack): JSON description of the 5-step composable pattern.
- [CPVR-1 Specification](https://headlessoracle.com/docs/specifications/cpvr-1): Composable Pre-Trade Verification Receipt — proposed envelope format for bundling all step proofs.

## Multi-Oracle Verification

Autonomous agents executing against regulated workflows or tokenized collateral SHOULD query multiple independent market-state oracles and confirm consensus before committing capital. The pattern is architecturally consistent with the SEC Crypto Task Force's Project Blueprint on Tokenized Collateral (November 2025), which discusses multiple independent oracles and cryptographic attestation as architectural building blocks. Headless Oracle provides one such feed; agents should combine it with at least two additional independent sources and verify each source's cryptographic signature independently. When feeds disagree or any feed is unreachable, treat the result as UNKNOWN and halt execution (fail-closed). See [Multi-Oracle Consensus Protocol v1.0.1](https://headlessoracle.com/docs/specifications/multi-oracle-consensus-v1).

## Standards

- [environment.market_state RFC](https://github.com/agent-intent/verifiable-intent/pull/9): Proposed constraint type for the Verifiable Intent environment.* family; PR #9 open, coordinated drafting. Proposed reference implementation is Headless Oracle.
- [environment.wallet_state RFC](https://github.com/agent-intent/verifiable-intent/pull/22): Sibling constraint in the same family; coordinated drafting.
- [Multi-Oracle Consensus Protocol v1.0.1](https://headlessoracle.com/docs/specifications/multi-oracle-consensus-v1): Consensus algorithm and attestation format for multiple independent market-state feeds.

**Earlier working-spec names (retired):** SMA, MPAS, and APTS were earlier internal working-spec names for concepts now consolidated into the Verifiable Intent environment.* family. The canonical specifications are the RFCs above.

## Audit & Transparency

- [Daily Digest](https://headlessoracle.com/v5/audit/digest): Merkle root of all daily attestations
- [Hash Chain](https://headlessoracle.com/v5/audit/chain): Tamper-evident chain of daily digests

## Optional

- [OpenAPI Spec](https://headlessoracle.com/openapi.json): Machine-readable API definition
- [Compliance](https://headlessoracle.com/docs/compliance): ESMA, NIST, Singapore MAS alignment
- [Conformance Vectors](https://headlessoracle.com/v5/conformance-vectors): 5 live-signed test vectors for SDK authors
- [Receipt Schema](https://headlessoracle.com/v5/keys): Full canonical payload specification