langchain-headless-oracle

LangChain tools for Headless Oracle: signed market-state receipts for autonomous agents.

Note: SMA in this package denotes "Signed Market Attestation" — not Simple Moving Average.

Installation

pip install langchain-headless-oracle

Quickstart

from langchain_headless_oracle import (
    MarketStatusTool,
    MarketScheduleTool,
    MarketStateVerifyTool,
)

# API key resolves from HEADLESS_ORACLE_API_KEY by default
# (or pass api_key=... to the constructor).
tools = [
    MarketStatusTool(),       # authenticated live receipt
    MarketScheduleTool(),     # keyless next open/close
    MarketStateVerifyTool(),  # keyless signature verification
]

Tools

MarketStatusTool

Returns a cryptographically signed Signed Market Attestation (SMA) receipt for one of 28 global exchanges.

• Status: OPEN, CLOSED, HALTED, or UNKNOWN
• Fail-closed: UNKNOWN and HALTED MUST be treated as CLOSED
• Signed: Ed25519, 60-second TTL
• Authenticated: requires an API key (see API key resolution)

MarketScheduleTool

Returns upcoming open/close times for a global exchange. IANA timezone identifiers — DST is handled automatically. Keyless.

MarketStateVerifyTool

Cryptographically verifies an SMA receipt's Ed25519 signature against Headless Oracle's published public keys at /v5/keys. Keyless.

Returns {valid: bool, reason: str | null}. Fail reasons include INVALID_SIGNATURE, EXPIRED, MISSING_FIELDS, UNKNOWN_KEY, INVALID_JSON.

Verification example

The status → verify pattern: fetch a receipt, verify it before acting on it.

import json
from langchain_headless_oracle import MarketStatusTool, MarketStateVerifyTool

receipt_json = MarketStatusTool()._run("XNYS")
verify_json = MarketStateVerifyTool()._run(receipt_json)
verified = json.loads(verify_json)

if not verified["valid"]:
    raise RuntimeError(f"Receipt rejected: {verified['reason']}")

receipt = json.loads(receipt_json)
if receipt["status"] != "OPEN":
    raise RuntimeError(f"Market not open: {receipt['status']} — halting execution")

API key resolution

MarketStatusTool resolves an API key in this priority order:

1. HEADLESS_ORACLE_API_KEY environment variable.
2. ~/.headless_oracle/config.json cache.
3. (Opt-in only) auto-provision a free sandbox key from https://headlessoracle.com/v5/sandbox.

Auto-provision is off by default — instantiate with auto_provision_sandbox=True to enable:

MarketStatusTool(auto_provision_sandbox=True)

When no key is available and auto-provision is off, the tool returns a fail-closed result instead of raising:

{"status": "UNKNOWN", "safe_to_execute": false, "error": "No API key found..."}

MarketScheduleTool and MarketStateVerifyTool do not require an API key.

Relationship to the Headless Oracle SDK

This package wraps the official headless_oracle Python SDK — all HTTP calls and Ed25519 verification are delegated to it.

This package supersedes the older headless-oracle-langchain package on PyPI, which will be deprecated.

Supported exchanges (28)

XNYS (NYSE), XNAS (NASDAQ), XLON (LSE), XJPX (Tokyo), XPAR (Paris), XHKG (Hong Kong), XSES (Singapore), XASX (Sydney), XBOM (BSE India), XNSE (NSE India), XSHG (Shanghai), XSHE (Shenzhen), XKRX (Seoul), XJSE (Johannesburg), XBSP (B3 Brazil), XSWX (Swiss), XMIL (Milan), XIST (Istanbul), XSAU (Riyadh), XDFM (Dubai), XNZE (Auckland), XHEL (Helsinki), XSTO (Stockholm), XCBT (CME), XNYM (NYMEX), XCBO (Cboe), XCOI (Coinbase 24/7), XBIN (Binance 24/7)

Links

• Docs
• LangChain integration guide
• SMA Protocol RFC-001
• headless_oracle Python SDK