headless-oracle (Python SDK)

Prevent your trading bot from executing orders against closed, halted, or holiday-closed markets. Handles thousands of schedule edge cases per year across 28 global exchanges (equities, derivatives, and 24/7 crypto). See /v5/exchanges for the live directory.

Built on Headless Oracle V5 — every status assertion is Ed25519-signed and expires in 60 seconds, so stale receipts never reach your execution layer.

Installation

pip install headless-oracle

With LangChain integration:

pip install "headless-oracle[langchain]"

With CrewAI integration:

pip install "headless-oracle[crewai]"

Quick start

from headless_oracle import OracleClient, verify

client = OracleClient(api_key="ok_live_...")

# Fetch a signed receipt and verify it
receipt = client.get_status("XNYS")
result = verify(receipt)

if not result.valid:
    raise RuntimeError(f"Receipt invalid: {result.reason}")

# Fail-closed: treat anything that isn't OPEN as CLOSED
if receipt["status"] != "OPEN":
    print("Market is not open — halting all execution")
else:
    print("Market is OPEN — proceed with trading logic")

Verification without a network call

For high-throughput use cases, pass the public key directly to skip the key registry fetch:

PUBLIC_KEY = "03dc27993a2c90856cdeb45e228ac065f18f69f0933c917b2336c1e75712f178"

result = verify(receipt, public_key=PUBLIC_KEY)

Batch queries

receipts = client.get_batch(["XNYS", "XNAS", "XLON"])
for r in receipts["receipts"]:
    print(r["mic"], r["status"])

Verifying receipt fields

Always treat UNKNOWN as CLOSED. It means the oracle encountered an internal error and failed safely.

Integrations

• LangChain tool
• CrewAI tool

Supported exchanges

License

MIT