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, orUNKNOWN - Fail-closed:
UNKNOWNandHALTEDMUST be treated asCLOSED - 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:
HEADLESS_ORACLE_API_KEYenvironment variable.~/.headless_oracle/config.jsoncache.- (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
Metadata
Release files for langchain-headless-oracle 0.1.0
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 |
|---|---|---|---|---|
| langchain_headless_oracle-0.1.0.tar.gz | 9.2 kB | Without provenance | Details for langchain_headless_oracle-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| langchain_headless_oracle-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for langchain_headless_oracle-0.1.0-py3-none-any.whl |
Total release size: 17.8 kB
Release files / langchain_headless_oracle-0.1.0.tar.gz
| Download URL | langchain_headless_oracle-0.1.0.tar.gz |
|---|---|
| Size | 9.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
4ef9d568c896a312c95a621d4f683e515765cf92d01cb7c3b959aad30b5d9b08
|
|
BLAKE2b-256 checksum How to use checksums |
fe280d62c0747e974f000dd83e7b6f8ade345f40d45baa7a324bc5e120b9d27d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Release files / langchain_headless_oracle-0.1.0-py3-none-any.whl
| Download URL | langchain_headless_oracle-0.1.0-py3-none-any.whl |
|---|---|
| Size | 8.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
54a611f28019f8424ba865ec9a31e0fd131b732d3f1a75408056ba3ebfee407d
|
|
BLAKE2b-256 checksum How to use checksums |
4c89d67d55ff7a5c7a8341768e9677cd22a3dd58bfeca8b96e68b389404c2222
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.2
|
Security for langchain-headless-oracle 0.1.0
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.