Headless Oracle

{
  "schemaVersion": "1.0",
  "humanReadableId": "lembagang/headless-oracle",
  "agentVersion": "5.0.0",
  "name": "Headless Oracle",
  "version": "v5.0",
  "description": "Proposed reference implementation of environment.market_state \u2014 open as PR #9 on Mastercard's Verifiable Intent repo and described in the IETF I-D for the environment.* family. Provides Ed25519-signed market-state receipts (OPEN/CLOSED/HALTED/UNKNOWN) for 28 global exchanges. Autonomous agents gate trade execution on cryptographically verified market state. Composes with environment.wallet_state for multi-venue mandates. Fail-closed: UNKNOWN always means CLOSED.",
  "url": "https://headlessoracle.com",
  "provider": {
    "organization": "LembaGang",
    "url": "https://headlessoracle.com"
  },
  "documentationUrl": "https://headlessoracle.com/docs",
  "privacyPolicyUrl": "https://headlessoracle.com/privacy",
  "termsOfServiceUrl": "https://headlessoracle.com/terms",
  "quickstartUrl": "https://headlessoracle.com/docs/quickstart",
  "capabilities": {
    "a2aVersion": "1.0",
    "streaming": false,
    "pushNotifications": false,
    "stateTransitionHistory": false
  },
  "authSchemes": [
    {
      "scheme": "api_key",
      "description": "API key in X-Oracle-Key header",
      "header_name": "X-Oracle-Key"
    },
    {
      "scheme": "bearer_token",
      "description": "OAuth 2.0 Bearer token (RFC 6749 client_credentials grant)"
    },
    {
      "scheme": "oauth2",
      "description": "OAuth 2.0 token endpoint",
      "tokenUrl": "https://headlessoracle.com/oauth/token",
      "scopes": [
        "oracle:read"
      ]
    }
  ],
  "authentication": {
    "schemes": [
      "bearer",
      "apiKey",
      "x402"
    ],
    "credentials": "https://headlessoracle.com/v5/keys/request"
  },
  "defaultInputModes": [
    "application/json"
  ],
  "defaultOutputModes": [
    "application/json"
  ],
  "tags": [
    "finance",
    "market-data",
    "pre-trade",
    "safety",
    "ed25519",
    "signed-receipts",
    "fail-closed",
    "mcp",
    "x402",
    "autonomous-agents"
  ],
  "skills": [
    {
      "id": "get_market_status",
      "name": "Get Market Status",
      "description": "Pre-trade verification gate: returns Ed25519-signed market-state receipt (OPEN/CLOSED/HALTED/UNKNOWN) for any of 28 global exchanges. Use before any financial execution, capital commitment, or market-dependent workflow. UNKNOWN and HALTED must be treated as CLOSED (fail-closed). Receipt includes attestation_ref (signature) for x402 payment flows and audit trails. 60-second TTL.",
      "tags": [
        "finance",
        "market-data",
        "safety",
        "signed-receipt",
        "fail-closed"
      ],
      "examples": [
        "Is NYSE open right now?",
        "Verify XLON is trading before executing this payment"
      ],
      "inputModes": [
        "application/json"
      ],
      "outputModes": [
        "application/json"
      ]
    },
    {
      "id": "get_market_schedule",
      "name": "Get Market Schedule",
      "description": "Returns holiday-aware trading session schedule: next open/close UTC times, market hours, trading hours, exchange operating hours, holiday calendar, lunch break windows (XJPX/XHKG/XSHG/XSHE), and session status across 28 exchanges.",
      "tags": [
        "finance",
        "schedule",
        "market-hours"
      ],
      "examples": [
        "When does Tokyo Stock Exchange open next?",
        "What are XJPX trading hours?"
      ],
      "inputModes": [
        "application/json"
      ],
      "outputModes": [
        "application/json"
      ]
    },
    {
      "id": "list_exchanges",
      "name": "List Exchanges",
      "description": "Returns directory of all 28 supported exchanges with MIC codes, names, IANA timezones, and exchange operating hours metadata. Use at agent startup to discover supported markets before calling get_market_status or get_market_schedule.",
      "tags": [
        "finance",
        "exchange-directory"
      ],
      "examples": [
        "Which exchanges does this oracle cover?"
      ],
      "inputModes": [
        "application/json"
      ],
      "outputModes": [
        "application/json"
      ]
    },
    {
      "id": "verify_receipt",
      "name": "Verify Receipt Signature",
      "description": "Verifies Ed25519 cryptographic proof on a Signed Market Attestation receipt \u2014 confirms genuine pre-trade verification attestation, receipt authenticity, and signature validity. REST endpoint for test harnesses and SDK authors; agents SHOULD prefer offline verification with the published public key.",
      "endpoint": "/v5/verify",
      "method": "POST",
      "auth": false,
      "tags": [
        "finance",
        "verification",
        "cryptography",
        "trust",
        "rest-only"
      ]
    },
    {
      "id": "get_sandbox_key",
      "name": "Get Sandbox Key",
      "description": "Provision a 7-day API key (200 calls). POST { \"email\": \"you@example.com\" } \u2014 email required, one per address.",
      "endpoint": "/v5/sandbox",
      "method": "POST",
      "auth": false,
      "input": {
        "email": {
          "type": "string",
          "required": true,
          "description": "Email address \u2014 key is sent to this address"
        }
      },
      "output": {
        "type": "object",
        "properties": {
          "api_key": {
            "type": "string",
            "description": "Sandbox API key (sb_ prefix)"
          },
          "tier": {
            "type": "string",
            "enum": [
              "sandbox"
            ]
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "calls_remaining": {
            "type": "integer"
          }
        }
      }
    }
  ],
  "fail_closed": true,
  "supported_exchanges": [
    "XNYS",
    "XNAS",
    "XLON",
    "XJPX",
    "XPAR",
    "XHKG",
    "XSES",
    "XASX",
    "XBOM",
    "XNSE",
    "XSHG",
    "XSHE",
    "XKRX",
    "XJSE",
    "XBSP",
    "XSWX",
    "XMIL",
    "XIST",
    "XSAU",
    "XDFM",
    "XNZE",
    "XHEL",
    "XSTO",
    "XCBT",
    "XNYM",
    "XCBO",
    "XCOI",
    "XBIN"
  ],
  "input_schema": {
    "type": "object",
    "properties": {
      "mic": {
        "type": "string",
        "description": "ISO 10383 Market Identifier Code",
        "examples": [
          "XNYS",
          "XLON",
          "XJPX"
        ]
      }
    },
    "required": [
      "mic"
    ]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "mic": {
        "type": "string"
      },
      "status": {
        "type": "string",
        "enum": [
          "OPEN",
          "CLOSED",
          "HALTED",
          "UNKNOWN"
        ]
      },
      "timestamp": {
        "type": "string",
        "format": "date-time"
      },
      "expires_at": {
        "type": "string",
        "format": "date-time",
        "description": "Receipt invalid after this time. Re-fetch required."
      },
      "issuer": {
        "type": "string",
        "example": "headlessoracle.com"
      },
      "key_id": {
        "type": "string",
        "example": "key_2026_v1"
      },
      "receipt_mode": {
        "type": "string",
        "enum": [
          "demo",
          "live"
        ]
      },
      "schema_version": {
        "type": "string",
        "example": "v5.0"
      },
      "signature": {
        "type": "string",
        "description": "Hex-encoded Ed25519 signature over canonical payload (alphabetical key sort, compact JSON)"
      }
    },
    "required": [
      "mic",
      "status",
      "timestamp",
      "expires_at",
      "issuer",
      "key_id",
      "receipt_mode",
      "schema_version",
      "signature"
    ]
  },
  "endpoints": {
    "mcp": "https://headlessoracle.com/mcp",
    "rest": "https://headlessoracle.com/v5/status",
    "oauth": "https://headlessoracle.com/oauth/token",
    "introspect": "https://headlessoracle.com/oauth/introspect",
    "openapi": "https://headlessoracle.com/openapi.json"
  },
  "x402_payable": true,
  "payment": {
    "schemes": [
      "x402"
    ],
    "network": "eip155:8453",
    "chain_id": 8453,
    "currency": "USDC",
    "amount_per_request": "0.001 USDC",
    "amount_units": "1000",
    "batch_amount_units": "5000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payment_endpoint": "https://headlessoracle.com/v5/status",
    "subscription_endpoint": "https://headlessoracle.com/v5/checkout",
    "mint_endpoint": "https://headlessoracle.com/v5/x402/mint",
    "discovery": "https://headlessoracle.com/.well-known/x402.json",
    "free_tier_daily_limit": 500
  },
  "standards": {
    "verifiable_intent": {
      "family": "environment.*",
      "upstream_repo": "agent-intent/verifiable-intent",
      "role": "proposed reference implementation of environment.market_state (PR #9, open)",
      "pull_requests": [
        {
          "constraint": "environment.market_state",
          "pr": 9,
          "url": "https://github.com/agent-intent/verifiable-intent/pull/9",
          "status": "coordinated drafting"
        },
        {
          "constraint": "environment.wallet_state",
          "pr": 22,
          "url": "https://github.com/agent-intent/verifiable-intent/pull/22",
          "status": "coordinated drafting"
        }
      ]
    },
    "predecessor_specs": {
      "note": "SMA, APTS, and MPAS were earlier working-spec names for concepts now incorporated into the Verifiable Intent environment.* family. Preserved for citation continuity; brand names retired.",
      "sma_protocol": "https://github.com/LembaGang/sma-protocol",
      "apts_standard": "https://github.com/LembaGang/agent-pretrade-safety-standard",
      "mpas_spec": "https://github.com/LembaGang/mpas-spec"
    },
    "conformance_vectors": "https://api.headlessoracle.com/v5/conformance-vectors",
    "implementations_registry": "https://headlessoracle.com/v5/implementations",
    "sma_disambiguation": "SMA denotes Signed Market Attestation, not Simple Moving Average"
  },
  "dst_aware": true,
  "discovery_url": "https://headlessoracle.com/.well-known/agent.json",
  "skill_url": "https://headlessoracle.com/skill.md",
  "erc8004": "8453:38413",
  "ampersend": "https://app.ampersend.ai/agents/headless-oracle",
  "pre_trade_stack": {
    "spec_url": "https://headlessoracle.com/docs/specifications/pre-trade-stack",
    "json_url": "https://headlessoracle.com/v5/pre-trade-stack",
    "pattern": "Composable Pre-Trade Verification Pattern (v2.0)",
    "role": "execution-environment verification (environment.market_state)",
    "composes_with": {
      "environment_wallet_state": "https://github.com/agent-intent/verifiable-intent/pull/22",
      "spend_authorization": "vendor-specific integration examples (e.g. Ampersend)",
      "signal_verification": "vendor-specific integration examples (e.g. VeroQ)",
      "payment": "x402 (Linux Foundation)"
    }
  },
  "mcp": {
    "endpoint": "https://headlessoracle.com/mcp",
    "protocol_version": "2024-11-05",
    "tools": [
      {
        "name": "get_market_status",
        "description": "Pre-trade verification gate: Ed25519-signed market-state receipt (OPEN/CLOSED/HALTED/UNKNOWN) for 28 exchanges. Use before any trade execution, capital commitment, or financial workflow. UNKNOWN/HALTED = CLOSED (fail-closed). Includes attestation_ref for x402 payment flows.",
        "parameters": {
          "mic": "string (required) \u2014 ISO 10383 MIC code, e.g. XNYS"
        }
      },
      {
        "name": "get_market_schedule",
        "description": "Holiday-aware trading session schedule: next open/close UTC times, market hours, exchange operating hours, holiday calendar, lunch breaks (XJPX/XHKG/XSHG/XSHE), session status for 28 exchanges.",
        "parameters": {
          "mic": "string (required) \u2014 ISO 10383 MIC code"
        }
      },
      {
        "name": "list_exchanges",
        "description": "Directory of all 28 supported exchanges: MIC codes, names, timezones, exchange operating hours metadata. Call at agent startup to discover all supported MIC codes.",
        "parameters": {}
      }
    ]
  },
  "rest_api": {
    "base_url": "https://headlessoracle.com",
    "openapi_spec": "https://headlessoracle.com/openapi.json",
    "endpoints": [
      {
        "path": "/v5/demo",
        "method": "GET",
        "auth": false,
        "description": "Public signed receipt"
      },
      {
        "path": "/v5/status",
        "method": "GET",
        "auth": true,
        "description": "Authenticated signed receipt"
      },
      {
        "path": "/v5/batch",
        "method": "GET",
        "auth": true,
        "description": "Batch signed receipts for multiple MICs"
      },
      {
        "path": "/v5/schedule",
        "method": "GET",
        "auth": false,
        "description": "Next open/close times"
      },
      {
        "path": "/v5/exchanges",
        "method": "GET",
        "auth": false,
        "description": "All supported exchanges"
      },
      {
        "path": "/mics.json",
        "method": "GET",
        "auth": false,
        "description": "All 28 supported MICs with exchange metadata and ISO 20022 registry links"
      },
      {
        "path": "/v5/archive",
        "method": "GET",
        "auth": false,
        "description": "Historical receipt archive (Builder+: 30-day; sandbox/free: today only)"
      },
      {
        "path": "/v5/stream",
        "method": "GET",
        "auth": true,
        "description": "SSE stream of signed market_status events every 30s via StreamCoordinator Durable Object"
      },
      {
        "path": "/v5/conformance-vectors",
        "method": "GET",
        "auth": false,
        "description": "Live-signed canonical test vectors for SDK authors (5 vectors: XNYS OPEN/CLOSED, XJPX lunch, UNKNOWN, HEALTH OK)"
      },
      {
        "path": "/v5/keys",
        "method": "GET",
        "auth": false,
        "description": "Public key registry + canonical payload spec"
      },
      {
        "path": "/v5/health",
        "method": "GET",
        "auth": false,
        "description": "Signed liveness probe"
      },
      {
        "path": "/.well-known/oracle-keys.json",
        "method": "GET",
        "auth": false,
        "description": "RFC 8615 key discovery"
      },
      {
        "path": "/v5/compliance",
        "method": "GET",
        "auth": false,
        "description": "APTS compliance self-report \u2014 6 pre-trade safety checks"
      },
      {
        "path": "/v5/metrics",
        "method": "GET",
        "auth": false,
        "description": "MCP client telemetry \u2014 today's request and unique client counts"
      },
      {
        "path": "/v5/dst-risk",
        "method": "GET",
        "auth": false,
        "description": "DST transition risk \u2014 affected European exchanges, error windows, verified XLON schedule"
      },
      {
        "path": "/v5/traction",
        "method": "GET",
        "auth": false,
        "description": "Live traction metrics \u2014 exchanges, uptime, MCP usage, stack positioning"
      },
      {
        "path": "/v5/metrics/public",
        "method": "GET",
        "auth": false,
        "description": "Social-proof metrics \u2014 exchanges, uptime_days, tests_passing, signing_algorithm, x402 stats, MCPScoreboard preflight score"
      },
      {
        "path": "/v5/usage",
        "method": "GET",
        "auth": true,
        "description": "Per-key usage stats \u2014 requests today/month, limits, credits, upgrade info"
      },
      {
        "path": "/v5/changelog",
        "method": "GET",
        "auth": false,
        "description": "Versioned changelog \u2014 entries[], each with date, version, changes[]"
      },
      {
        "path": "/badge/:mic",
        "method": "GET",
        "auth": false,
        "description": "SVG status badge for README embedding (shields.io style)"
      }
    ],
    "auth": {
      "header": "X-Oracle-Key",
      "missing": 401,
      "invalid": 403,
      "payment_required": 402
    }
  },
  "trust": {
    "algorithm": "Ed25519",
    "key_id_prefix": "03dc2799",
    "key_registry": "https://headlessoracle.com/v5/keys",
    "well_known": "https://headlessoracle.com/.well-known/oracle-keys.json",
    "verify_sdk": "npm:@headlessoracle/verify"
  },
  "safety": {
    "fail_closed": true,
    "unknown_means": "CLOSED \u2014 halt all execution",
    "receipt_ttl_sec": 60
  }
}