# Headless Oracle

> Cryptographically signed market state verification for autonomous financial agents. Ed25519-signed receipts ("SMA receipts") for 28 global exchanges — equities, derivatives, and 24/7 crypto. MCP-native, A2A-discoverable, x402-payable, fail-closed. UNKNOWN always means CLOSED.

**In this documentation, SMA denotes "Signed Market Attestation" — not the statistical "Simple Moving Average" used in technical analysis.**

## Role in the Verifiable Intent Environment.* Family

Headless Oracle is the reference implementation of environment.market_state, a proposed constraint type in the Verifiable Intent (VI) specification's environment.* namespace. The environment.* family addresses a class of vulnerability in autonomous Layer 3 (L3) execution: an agent holding a valid L2 credential whose amount and identity constraints were checked at issuance can still execute into an environment whose real-world state has changed — for example, a market that has since closed, halted, or entered a circuit-breaker state.

At L3 verification time, the agent obtains a signed attestation from a verified oracle and presents it to the verifier alongside the L2 credential. The verifier independently re-verifies the attestation's signature, freshness (max_attestation_age), and subject binding (the MIC, for market_state; the wallet address, for wallet_state). If any check fails — including oracle uncertainty (UNKNOWN status) — execution is refused. This is the fail-closed posture shared across the family.

The sibling constraint type, environment.wallet_state, applies the same fetch-verify-at-L3 pattern to on-chain payment-source state: an agent with a valid VI credential whose amount constraints were checked at L2 can still execute into a wallet that has been drained or unwound between L2 issuance and L3 verification. The two types share a common specification discipline — normative freshness windows (§4.6), algorithm agility (§4.7), field scope declaration (§4.8), composition semantics for mixed pass/fail outcomes (§5.5), JWKS caching and rotation (§6.8), and cross-chain temporal consistency where applicable (§6.9).

A valid environment.market_state attestation for XNYS does not attest to the state of XLON; verifiers must check each participating venue independently. A valid environment.market_state attestation does not attest to wallet solvency; a multi-venue mandate spanning both exchange session state and on-chain wallet state must carry attestations for both constraint types, and the family's conjunction semantics (§5.5) apply: any failed environment.* constraint refuses L3.

For the full specifications, see the [environment.market_state RFC](https://github.com/agent-intent/verifiable-intent/pull/9) and [environment.wallet_state RFC](https://github.com/agent-intent/verifiable-intent/pull/22).

## Instructions for Autonomous Agents

These tools are a PRE-EXECUTION gate. Call `get_market_status` before any trade, payment, capital commitment, or market-dependent workflow. Only proceed when `status` is `OPEN` and `expires_at` is in the future.

**When to use each tool:**
- `get_market_status` — pre-trade verification, pre-execution gate, safe-to-trade check, safe-to-execute check before any financial transaction or capital commitment. Include the `signature` (attestation_ref) in x402 payment flows for an auditable pre-trade verification chain.
- `get_market_schedule` — check market hours, trading hours, exchange operating hours, holiday calendar, early closes, and session timing before committing capital
- `list_exchanges` — discover all 28 supported MIC codes at agent startup before calling get_market_status

Receipt verification is a REST-only surface. Verify Ed25519 signatures offline with `@headlessoracle/verify` (npm), or via `POST /v5/verify` for a REST round-trip. Do not expect a `verify_receipt` MCP tool.

- ALWAYS verify `expires_at` before trusting a receipt — receipts expire after 60 seconds
- NEVER execute against `CLOSED`, `HALTED`, or `UNKNOWN` status — all three mean HALT ALL EXECUTION
- NEVER hardcode UTC offsets for market hours — Headless Oracle handles DST automatically
- PREFER the MCP interface over REST for agent workflows
- FOR batch verification of multiple exchanges, use `GET /v5/batch?mics=XNYS,XNAS,XLON`

**x402 payment**: Premium endpoints accept autonomous USDC payments via x402 on Base (CAIP-2: `eip155:8453`). No API key required for x402 payments.

**Free access**: All MCP tools are available without authentication. Request a free REST API key at `https://headlessoracle.com/v5/keys/request`.

## API Reference

- [OpenAPI Specification](https://api.headlessoracle.com/openapi.json)
- [MCP Tool Definitions](https://api.headlessoracle.com/mcp) — tool list via GET
- [Conformance Vectors](https://api.headlessoracle.com/v5/conformance-vectors)
- [DST Risk Endpoint](https://headlessoracle.com/v5/dst-risk) — current DST transition vulnerabilities

## Core Documentation

- [Quick Start (.mcp.json setup)](https://headlessoracle.com/docs/quickstart)
- [Full Documentation](https://headlessoracle.com/docs)
- [MCP Integration Guide](https://headlessoracle.com/docs/integrations/mcp)
- [LangChain Integration](https://headlessoracle.com/docs/integrations/langchain)
- [CrewAI Integration](https://headlessoracle.com/docs/integrations/crewai)
- [REST API Reference](https://headlessoracle.com/docs/api)
- [Receipt Verification](https://headlessoracle.com/docs/verification)
- [SMA Protocol RFC-001](https://headlessoracle.com/docs/sma-protocol/rfc-001) — earlier working-spec name for what is now `environment.market_state` in the Verifiable Intent environment.* family. The RFCs linked above are the canonical specifications.
- [Multi-Party Attestation Spec (MPAS-1.0)](https://github.com/LembaGang/mpas-spec) — earlier working-spec name; the concepts are now consolidated into the Verifiable Intent environment.* family and related constraint types.
- Known implementations across SMA, MPAS, and APTS: GET /v5/implementations (public). Submit yours via the submit_url field. Note: SMA/MPAS/APTS are retired working-spec names; see the RFCs above for canonical specifications.

## SDK Documentation

- [JavaScript/TypeScript (@headlessoracle/verify)](https://headlessoracle.com/docs/sdks/javascript)
- [Python (headless-oracle)](https://headlessoracle.com/docs/sdks/python)
- [Go (headless-oracle-go)](https://headlessoracle.com/docs/sdks/go)

## Quick Start
# Path A — email sandbox (human onboarding):
POST https://api.headlessoracle.com/v5/sandbox
Body: { "email": "you@example.com" }
→ Returns sb_ key (7 days, 200 calls)

# Path B — x402 agent onboarding (no email, no human):
POST https://api.headlessoracle.com/v5/sandbox
Header: X-Payment: {"txHash":"0x...","network":"base","amount":"1000","paymentAddress":"0x26D4...","memo":""}
→ Verifies $0.001 USDC payment on Base mainnet → Returns ho_crd_ credit key (10 credits, no expiry)

# Path C — per-request x402 (no key ever needed):
GET https://api.headlessoracle.com/v5/status?mic=XNYS → 402 with payment details
GET https://api.headlessoracle.com/v5/status?mic=XNYS + X-Payment header → 200 signed receipt

# Path D — mint persistent key (99 USDC builder / 299 USDC pro):
POST https://api.headlessoracle.com/v5/x402/mint
Body: { "tx_hash": "0x...", "tier": "builder" }
→ Returns ho_live_ key (50,000 calls/day, no expiry)

# Demo (signed receipt, no key needed):
GET https://api.headlessoracle.com/v5/demo?mic=XNYS

## Endpoints
| Endpoint | Method | Auth | Description | Returns |
|---|---|---|---|---|
| /v5/demo | GET | No | Signed receipt, demo mode | SMA receipt (receipt_mode=demo) |
| /v5/status | GET | Yes | Signed receipt, live mode | SMA receipt (receipt_mode=live) |
| /v5/batch | GET | Yes | Signed receipts for multiple MICs | { summary, receipts[] } |
| /v5/sandbox | POST | No | Sandbox key via email OR credit key via x402 payment ($0.001) | { api_key, tier, ...} |
| /v5/schedule | GET | No | Next open/close times (not signed) | { next_open, next_close, lunch_break, settlement_window } |
| /v5/exchanges | GET | No | All 28 supported exchanges | { exchanges: [{mic, name, timezone, mic_type}] } |
| /v5/keys | GET | No | Public signing key + canonical spec | { keys: [{key_id, public_key, algorithm}] } |
| /v5/health | GET | No | Signed liveness probe | SMA-format health receipt |
| /v5/usage | GET | Yes | Per-key daily usage stats | { requests_today, limit, percent_used } |
| /v5/traction | GET | No | Live metrics snapshot | { exchanges_covered, mcp_requests_today, ... } |
| /v5/metrics/public | GET | No | Social-proof metrics — exchanges, uptime_days, tests_passing, signing_algorithm, x402 stats, mcpscoreboard_preflight | stable facts, no auth |
| /v5/implementations | GET | No | Standards implementations registry (SMA/MPAS/APTS) | { standards: { sma, mpas, apts }, total_implementations } |
| /v5/showcase | GET | No | Reference projects using Headless Oracle | { entries: [{name, url, category}], submit_url } |
| /v5/receipts | GET | Builder+ | Receipt audit log | { receipts: [{mic, status, issued_at}] } |
| /v5/dst-risk | GET | No | DST transition risk for affected exchanges | { event, affected_exchanges[], risk_window_minutes } |
| /v5/webhooks/subscribe | POST | Yes | Subscribe to state-change webhooks | { subscription_id } |
| /v5/webhooks/unsubscribe | DELETE | Yes | Remove webhook subscription | { ok: true } |
| /v5/archive | GET | Optional | Historical receipt archive | { mic, date, count, receipts[] } |
| /v5/audit/digest | GET | No | Daily attestation digest with Merkle root | { date, total_receipts_issued, merkle_root, chain_length } |
| /v5/audit/chain | GET | No | Hash chain of last 7 daily digests | { chain_length, chain_intact, digests[] } |
| /v5/stream | GET | Yes | SSE stream of signed market_status events every 30s | text/event-stream |
| /v5/conformance-vectors | GET | No | 5 live-signed canonical test vectors | { vectors: [{name, receipt, canonical_payload, public_key}] } |
| /mcp | POST | No (optional Bearer) | MCP Streamable HTTP (JSON-RPC 2.0) | JSON-RPC response |
| /openapi.json | GET | No | OpenAPI 3.1 machine-readable spec | OpenAPI document |
| /.well-known/oracle-keys.json | GET | No | RFC 8615 key discovery (hex public_key — source of truth for deployed SDKs) | Key lifecycle metadata + jwks_uri |
| /.well-known/jwks.json | GET | No | RFC 7517 JWKSet for JOSE-aware verifiers — discovery-only in this release | application/jwk-set+json |
| /.well-known/agent.json | GET | No | A2A Agent Card | A2A agent capabilities |
| /.well-known/mcp/server-card.json | GET | No | MCP server card | Tool list, reliability, coverage |
| /.well-known/security.txt | GET | No | RFC 9116 security contact | Contact, Expires, Preferred-Languages |
| /v5/errors/{code} | GET | No | Machine-readable error definition | { message, resolution, http_status } |
| /v5/changelog | GET | No | Versioned changelog feed | { version, updated, entries[] } |
| /badge/:mic | GET | No | SVG status badge | image/svg+xml |
| /status | GET | No | HTML market status page for all 28 exchanges | text/html |
| /v5/webhooks | GET | Yes | List all webhook subscriptions for this key | { webhooks: [{webhook_id, url, mics, events, status}], count } |
| /v5/webhooks/:id | DELETE | Yes | Delete a webhook subscription | 204 No Content |
| /v5/webhooks/test/:id | POST | Yes | Fire a synthetic test delivery to a webhook | { delivered, payload_sent, status_code } |
| /v5/webhooks/health | GET | No | WebhookDispatcher DO health (last alarm cycle) | { status, next_alarm } |
| /v5/card/:mic | GET | No | SVG terminal-style status card | image/svg+xml |
| /v5/x402/mint | POST | No | Mint persistent API key via Base USDC tx | { api_key, tier, daily_limit } |
| /v5/credits/purchase | POST | Yes | Add prepaid credits via x402 USDC payment | { credits_added, new_balance } |
| /v5/credits/balance | GET | Yes | Check prepaid credit balance | { balance, estimated_requests_remaining } |
| /v5/verify | POST | No | Ed25519 receipt verification (REST) | { valid, expired, reason, mic, status, expires_at } |
| /x402 | GET | No | x402 Foundation compatibility declaration | { x402_compatible, network, facilitator, first_payment_at } |

## Receipt Schema (SMA = Signed Market Attestation, not Simple Moving Average)
```json
{
  "receipt_id":     "uuid",
  "mic":            "XNYS",
  "status":         "OPEN | CLOSED | HALTED | UNKNOWN",
  "issued_at":      "2026-03-27T14:30:00.000Z",
  "expires_at":     "2026-03-27T14:31:00.000Z",
  "issuer":         "headlessoracle.com",
  "source":         "SCHEDULE | OVERRIDE | REALTIME | SYSTEM",
  "schema_version": "v5.0",
  "receipt_mode":   "demo | live",
  "public_key_id":  "key_2026_v1",
  "signature":      "<hex-encoded Ed25519 signature>"
}
```

## Verification
Ed25519 signature verification steps:
1. Receive receipt JSON
2. Extract all fields EXCEPT "signature" -> payload object
3. Sort payload keys alphabetically
4. JSON.stringify(sortedPayload) with no whitespace -> canonical string
5. Verify signature (hex) against canonical string using public key from /v5/keys
6. Check expires_at > now (60s TTL)
7. Check status === "OPEN" before proceeding
If any step fails -> halt execution

SDK (JS): npm install @headlessoracle/verify (zero deps, Web Crypto)
SDK (Go): go get github.com/LembaGang/headless-oracle-go (zero stdlib deps, oracle.Verify())
SDK (Python): pip install headless-oracle

## Supported Exchanges

### Equities (23)
XNYS (NYSE, America/New_York), XNAS (NASDAQ, America/New_York), XLON (London, Europe/London),
XJPX (Tokyo, Asia/Tokyo), XPAR (Paris, Europe/Paris), XHKG (Hong Kong, Asia/Hong_Kong),
XSES (Singapore, Asia/Singapore), XASX (Sydney, Australia/Sydney), XBOM (Mumbai BSE, Asia/Kolkata),
XNSE (Mumbai NSE, Asia/Kolkata), XSHG (Shanghai, Asia/Shanghai), XSHE (Shenzhen, Asia/Shanghai),
XKRX (Seoul, Asia/Seoul), XJSE (Johannesburg, Africa/Johannesburg), XBSP (Sao Paulo, America/Sao_Paulo),
XSWX (Zurich, Europe/Zurich), XMIL (Milan, Europe/Rome), XIST (Istanbul, Europe/Istanbul),
XSAU (Riyadh, Asia/Riyadh, Fri/Sat weekends), XDFM (Dubai, Asia/Dubai, Fri/Sat weekends),
XNZE (Auckland, Pacific/Auckland), XHEL (Helsinki, Europe/Helsinki), XSTO (Stockholm, Europe/Stockholm)

### Derivatives & Crypto (5)
XCBT (CME Futures, America/Chicago, overnight/Sunday pre-open, mic_type: iso)
XNYM (NYMEX, America/Chicago, overnight/Sunday pre-open, mic_type: iso)
XCBO (Cboe Options, America/Chicago, 9:30-16:15 ET, mic_type: iso)
XCOI (Coinbase, UTC, 24/7 no weekends, mic_type: convention)
XBIN (Binance, UTC, 24/7 no weekends, mic_type: convention)

settlement_window: T+1/DTCC (XNYS/XNAS), T+2/Euroclear (XLON), T+2/JSCC (XJPX), null for all others

## DST Risk (Critical: March 29, 2026)
European clocks spring forward Sunday March 29, 2026 at 01:00 UTC.
XLON, XPAR, XSWX, XMIL, XHEL, XSTO shift +1h (GMT/CET → BST/CEST).
Agents using hardcoded UTC offsets will compute incorrect market hours starting Monday March 30.
Headless Oracle receipts use IANA timezone identifiers — DST is handled automatically.
Live risk endpoint: GET https://headlessoracle.com/v5/dst-risk

## Fail-Closed Guarantee
UNKNOWN status means the oracle cannot determine market state. Agents MUST treat UNKNOWN as CLOSED and halt. HALTED means a circuit breaker or operator override is active — also treat as CLOSED. The absence of a valid signed receipt is itself proof of unsafety.

## Pricing
- Free: 500 req/day (GET /v5/keys/request)
- Sandbox: 200 req/7 days, email required (POST /v5/sandbox with { "email": "you@example.com" })
- x402: 0.001 USDC/req via Base mainnet (no key, no signup)
- Builder: 50,000 req/day ($99/mo)
- Pro: 200,000 req/day ($299/mo)
- Protocol: unlimited ($500/mo)
Upgrade: https://headlessoracle.com/upgrade

## Discovery Endpoints
- [Agent Card (A2A)](https://headlessoracle.com/.well-known/agent.json)
- [MCP Server Card](https://headlessoracle.com/.well-known/mcp/server-card.json)
- [Oracle Public Keys (hex, RFC 8615)](https://headlessoracle.com/.well-known/oracle-keys.json) — source of truth for deployed SDKs
- [JWKS (RFC 7517)](https://headlessoracle.com/.well-known/jwks.json) — discovery-only in this release; receipts do not yet carry a kid. Deployed SDKs (@headlessoracle/verify, headless-oracle) continue to verify against oracle-keys.json. JOSE-aware verifiers may use this endpoint for key discovery; kid-aware receipt verification is planned for a future major release.

## MCP Integration
Server card: GET https://headlessoracle.com/.well-known/mcp/server-card.json
Protocol: MCP-2024-11-05
Endpoint: POST https://headlessoracle.com/mcp
Tools: get_market_status, get_market_schedule, list_exchanges
Auth: optional Bearer token (Oracle API key via POST /oauth/token)

## IDE Setup Guides
- [Cline (VS Code)](https://headlessoracle.com/docs/cline) — VS Code Cline extension setup
- [Continue.dev](https://headlessoracle.com/docs/continue) — Continue.dev VS Code extension setup
- [Cursor](https://headlessoracle.com/docs/cursor-setup) — Cursor IDE setup
- [Windsurf](https://headlessoracle.com/docs/windsurf-config) — Windsurf IDE setup

## Agent Framework Integrations
- [Claude Managed Agents](https://headlessoracle.com/docs/integrations/claude-managed-agents) — Pre-trade verification gate for Anthropic's production agent hosting platform (MCP native, batch checks, audit trail)
- [Google ADK Integration](https://headlessoracle.com/docs/integrations/google-adk) — Google Agent Development Kit via McpToolset (stdio + HTTP transport)
- [TradingAgents Integration](https://headlessoracle.com/docs/integrations/trading-agents) — Pre-trade gate for TauricResearch/TradingAgents multi-agent framework
- [Agno Integration](https://headlessoracle.com/docs/integrations/agno) — Agno (22K stars) via MCPTools or Python SDK
- [Strands Integration](https://headlessoracle.com/docs/integrations/strands) — AWS Strands Agents SDK with first-party headless-oracle-strands PyPI package
- [Olas Integration](https://headlessoracle.com/docs/integrations/olas) — Pre-trade gate for Olas autonomous services
- [AutoGPT Integration](https://headlessoracle.com/docs/integrations/autogpt) — AutoGPT plugin for pre-trade verification
- [Ampersend Integration](https://headlessoracle.com/docs/integrations/ampersend) — Composable deployment pattern: execution-environment verification (environment.market_state) composed with spend authorization.

## Pre-Trade Verification Pattern
- [Pattern Specification v2.0](https://headlessoracle.com/docs/specifications/pre-trade-stack) — Composable deployment pattern: execution-environment verification → spend authorization → signal verification → payment → trade execution. Step 1 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: 5 steps, normative specification references, fail-closed composition semantics.
- [CPVR-1 Specification](https://headlessoracle.com/docs/specifications/cpvr-1) — Composable Pre-Trade Verification Receipt: proposed JSON envelope wrapping all step proofs into a single verifiable artifact.

## Blog
- [Market Hours APIs Are Not Enough for Autonomous Agents](https://headlessoracle.com/blog/market-hours-api-vs-signed-attestation) — Why boolean is_open fails agents; the signed attestation model
- [Why Your Trading Agent Needs a Pre-Trade Gate](https://headlessoracle.com/blog/why-your-trading-agent-needs-a-pre-trade-gate) — DST post-mortem and fail-closed contract

## Discovery
- [/.well-known/mcp-servers.json](https://headlessoracle.com/.well-known/mcp-servers.json) — Self-describing registry feed for MCP directories (auto-updateable, proposed convention)

## Blog
- [Why Your Trading Agent Needs a Pre-Trade Gate](https://headlessoracle.com/blog/why-your-trading-agent-needs-a-pre-trade-gate) — DST bug post-mortem and fail-closed contract

## MCP Client Configuration

Claude Desktop (~/.config/claude/claude_desktop_config.json):
```json
{
  "mcpServers": {
    "headless-oracle": {
      "command": "npx",
      "args": ["headless-oracle-mcp"]
    }
  }
}
```

Cursor (.cursor/mcp.json):
```json
{
  "mcpServers": {
    "headless-oracle": {
      "command": "npx",
      "args": ["headless-oracle-mcp"]
    }
  }
}
```

## Exchange Session Hours

| MIC | Exchange | Timezone | Open | Close | Lunch Break | Weekends |
|-----|----------|----------|------|-------|-------------|----------|
| XNYS | NYSE | America/New_York | 09:30 | 16:00 | — | Sat/Sun |
| XNAS | NASDAQ | America/New_York | 09:30 | 16:00 | — | Sat/Sun |
| XLON | London SE | Europe/London | 08:00 | 16:30 | — | Sat/Sun |
| XJPX | Tokyo SE | Asia/Tokyo | 09:00 | 15:00 | 11:30–12:30 | Sat/Sun |
| XPAR | Euronext Paris | Europe/Paris | 09:00 | 17:30 | — | Sat/Sun |
| XHKG | Hong Kong | Asia/Hong_Kong | 09:30 | 16:00 | 12:00–13:00 | Sat/Sun |
| XSES | Singapore | Asia/Singapore | 09:00 | 17:00 | — | Sat/Sun |
| XASX | ASX | Australia/Sydney | 10:00 | 16:00 | — | Sat/Sun |
| XBOM | BSE India | Asia/Kolkata | 09:15 | 15:30 | — | Sat/Sun |
| XNSE | NSE India | Asia/Kolkata | 09:15 | 15:30 | — | Sat/Sun |
| XSHG | Shanghai | Asia/Shanghai | 09:30 | 15:00 | 11:30–13:00 | Sat/Sun |
| XSHE | Shenzhen | Asia/Shanghai | 09:30 | 15:00 | 11:30–13:00 | Sat/Sun |
| XKRX | Korea Exchange | Asia/Seoul | 09:00 | 15:30 | — | Sat/Sun |
| XJSE | Johannesburg | Africa/Johannesburg | 09:00 | 17:00 | — | Sat/Sun |
| XBSP | B3 Brazil | America/Sao_Paulo | 10:00 | 17:00 | — | Sat/Sun |
| XSWX | SIX Swiss | Europe/Zurich | 09:00 | 17:30 | — | Sat/Sun |
| XMIL | Borsa Italiana | Europe/Rome | 09:00 | 17:30 | — | Sat/Sun |
| XIST | Borsa Istanbul | Europe/Istanbul | 10:00 | 18:00 | — | Sat/Sun |
| XSAU | Saudi Tadawul | Asia/Riyadh | 10:00 | 15:00 | — | Fri/Sat |
| XDFM | Dubai DFM | Asia/Dubai | 10:00 | 14:00 | — | Fri/Sat |
| XNZE | NZX | Pacific/Auckland | 10:00 | 16:45 | — | Sat/Sun |
| XHEL | Helsinki | Europe/Helsinki | 10:00 | 18:30 | — | Sat/Sun |
| XSTO | Stockholm | Europe/Stockholm | 09:00 | 17:30 | — | Sat/Sun |
| XCBT | CME Futures | America/Chicago | 17:00 | 16:00 | — | Sat/Sun |
| XNYM | NYMEX | America/Chicago | 17:00 | 16:00 | — | Sat/Sun |
| XCBO | Cboe Options | America/Chicago | 09:30 | 16:15 | — | Sat/Sun |
| XCOI | Coinbase | UTC | 00:00 | 24:00 | — | None |
| XBIN | Binance | UTC | 00:00 | 24:00 | — | None |

## curl Examples

```bash
# Free demo receipt (no auth)
curl https://headlessoracle.com/v5/demo?mic=XNYS

# Authenticated live receipt
curl -H "X-Oracle-Key: YOUR_KEY" https://headlessoracle.com/v5/status?mic=XNYS

# Multi-exchange batch
curl -H "X-Oracle-Key: YOUR_KEY" "https://headlessoracle.com/v5/batch?mics=XNYS,XNAS,XLON"

# Next session schedule
curl https://headlessoracle.com/v5/schedule?mic=XJPX

# Daily briefing
curl https://headlessoracle.com/v5/briefing
```

## Receipt Verification (JavaScript)

```javascript
import { verify } from '@headlessoracle/verify';

const res = await fetch('https://headlessoracle.com/v5/demo?mic=XNYS');
const { receipt } = await res.json();

const result = await verify(receipt);
if (!result.ok) throw new Error(result.reason);
if (receipt.status !== 'OPEN') throw new Error('Market not open — halt execution');
```

## Receipt Verification (Python)

```python
from headless_oracle import OracleClient

client = OracleClient()
receipt = client.get_status("XNYS")
if not client.verify(receipt):
    raise Exception("Signature verification failed")
if receipt["status"] != "OPEN":
    raise Exception("Market not open — halt execution")
```

## x402 Payment Flow

1. Agent calls GET /v5/status?mic=XNYS without auth → receives 402 with payment details
2. 402 body contains: payTo address, amount (1000 = $0.001 USDC), network (base), chainId (8453)
3. Agent signs USDC transfer on Base mainnet
4. Agent retries GET /v5/status?mic=XNYS with X-Payment header containing tx proof
5. Oracle verifies on-chain: receipt status, Transfer event, amount, recipient, block age (<300s)
6. Returns signed receipt on success

No API key needed. No signup. No human in the loop.

## Compliance Alignment

Regulatory direction on tokenized collateral and digital-asset derivatives is moving toward cryptographic attestation, multiple independent oracles, and verifiable data provenance as technical primitives. CFTC Staff Letter 25-39 (December 2025) provides technology-neutral guidance on tokenized collateral; the SEC Crypto Task Force's Project Blueprint on Tokenized Collateral (November 2025) discusses oracle governance and signed attestations as architectural building blocks. Final CFTC rulemaking on tokenized collateral is expected by August 2026. Signed Market-State Attestations provide the cryptographic evidence regulated parties need to incorporate authentic, timely venue state into their own compliance frameworks as the regulatory picture crystallizes.

The following frameworks are listed for architectural orientation. Operators MUST evaluate their own regulatory obligations independently; Headless Oracle is not a compliance product.

| Framework | Architectural Relevance | Headless Oracle Feature |
|-----------|------------------------|------------------------|
| CFTC Staff Letter 25-39 (Dec 2025) | Tokenized collateral, technology-neutral | Ed25519 signed attestations, 60s TTL |
| SEC Project Blueprint on Tokenized Collateral (Nov 2025) | Multiple oracles + cryptographic attestation | Multi-Oracle Consensus Protocol v1.0.1 |
| ESMA MiFID II | Pre-trade transparency | Signed receipts with Ed25519 |
| SOC 2 | Audit trail | Receipt audit log (/v5/receipts) |