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
| Field | Description |
|---|---|
receipt_id |
UUID, unique per receipt |
issued_at |
ISO 8601 UTC timestamp |
expires_at |
Act before this time (60s TTL) |
issuer |
"headlessoracle.com" — resolve {issuer}/v5/keys to find the public key |
mic |
Exchange MIC code (e.g. XNYS) |
status |
OPEN, CLOSED, HALTED, or UNKNOWN |
source |
SCHEDULE, OVERRIDE, or SYSTEM |
receipt_mode |
demo or live |
schema_version |
v5.0 |
public_key_id |
Key identifier (matches /v5/keys registry) |
signature |
128-char hex Ed25519 signature of canonical payload |
Always treat UNKNOWN as CLOSED. It means the oracle encountered an internal error and failed safely.
Integrations
Supported exchanges
| MIC | Exchange | Timezone |
|---|---|---|
| XNYS | New York Stock Exchange | America/New_York |
| XNAS | NASDAQ | America/New_York |
| XLON | London Stock Exchange | Europe/London |
| XJPX | Japan Exchange Group | Asia/Tokyo |
| XPAR | Euronext Paris | Europe/Paris |
| XHKG | Hong Kong Exchanges | Asia/Hong_Kong |
| XSES | Singapore Exchange | Asia/Singapore |
License
MIT
Metadata
Release files for headless-oracle 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| headless_oracle-0.1.1.tar.gz | 14.3 kB | Without provenance | Details for headless_oracle-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| headless_oracle-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for headless_oracle-0.1.1-py3-none-any.whl |
Total release size: 21.9 kB
Release files / headless_oracle-0.1.1.tar.gz
| Download URL | headless_oracle-0.1.1.tar.gz |
|---|---|
| Size | 14.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1f36018f39e2fda66b7167231f77e77800cea888f3a835e604e7b7a855513ceb
|
|
BLAKE2b-256 checksum How to use checksums |
28a96723a0da867fb5c488541038eab8d98c27e77c63e65c47ad9b92106a40b9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Release files / headless_oracle-0.1.1-py3-none-any.whl
| Download URL | headless_oracle-0.1.1-py3-none-any.whl |
|---|---|
| Size | 7.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
18b2e61a9b824bb05b75a598e2b6c4946fdaeca072c70927d43c4addd83211b3
|
|
BLAKE2b-256 checksum How to use checksums |
d99d5c06a40658effcf22e7404b1646975948897ff6080f06ba5a74179154edc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Security for headless-oracle 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.