headless-oracle-strands
Strands Agents SDK tools for Headless Oracle market state verification.
Note: SMA in this package denotes "Signed Market Attestation" — not Simple Moving Average.
pip install headless-oracle-strands
Quick Start
from headless_oracle_strands import get_market_status, get_market_schedule, list_exchanges
from strands import Agent
# Zero config — auto-provisions sandbox key on first tool call
agent = Agent(tools=[get_market_status, get_market_schedule, list_exchanges])
response = agent("Is the NYSE open right now? Should I execute my trade?")
print(response)
Tools
get_market_status
Returns a cryptographically signed Signed Market Attestation (SMA) receipt for a global exchange.
- Status:
OPEN,CLOSED,HALTED, orUNKNOWN - Fail-closed:
UNKNOWNandHALTEDMUST be treated asCLOSED - Signed: Ed25519 signature, 60-second TTL
- 28 exchanges: NYSE, NASDAQ, LSE, Tokyo, CME, Coinbase, and more
from headless_oracle_strands import get_market_status
# Direct invocation (outside an agent)
receipt = get_market_status(mic="XNYS")
# receipt["receipt"]["status"] → "OPEN" | "CLOSED" | "HALTED" | "UNKNOWN"
get_market_schedule
Returns next open/close times in UTC. DST-aware via IANA timezone identifiers.
from headless_oracle_strands import get_market_schedule
schedule = get_market_schedule(mic="XLON")
# schedule["next_open"] → "2026-03-31T08:00:00Z"
list_exchanges
Lists all 28 supported exchanges.
from headless_oracle_strands import list_exchanges
exchanges = list_exchanges()
# [{"mic": "XNYS", "name": "New York Stock Exchange", ...}, ...]
Attestation Helpers (x402 Payment Flows)
For agents that use x402 micropayments or need
a verifiable audit chain of oracle decisions, the attestation module provides composable
helpers for constructing attestation_ref objects.
from headless_oracle_strands import (
get_market_status,
attestation_ref_from_receipt,
is_market_open,
should_refetch,
)
# 1. Fetch oracle receipt
response = get_market_status(mic="XNYS", api_key="your_key")
# 2. Construct attestation_ref (binds receipt to this specific payment transaction)
ref = attestation_ref_from_receipt(response, x402_transaction_id="txn-abc123")
# 3. Fail-closed gate
if not is_market_open(ref):
raise RuntimeError(f"Market is {ref.status} — halting execution")
# 4. Check TTL before initiating x402 sequence
if should_refetch(ref):
# Receipt expires in < 5s — re-fetch before paying
response = get_market_status(mic="XNYS", api_key="your_key")
ref = attestation_ref_from_receipt(response, x402_transaction_id="txn-abc123")
# 5. Embed in payment event
payment_event = {
"action": "buy",
"quantity": 100,
"attestation_ref": ref.to_dict(), # auditable proof of market state
}
AWS AgentCore Integration
This package is the recommended Strands integration path for the AWS AgentCore x402 payments sample.
from strands import Agent
from headless_oracle_strands import (
get_market_status,
attestation_ref_from_receipt,
is_market_open,
compute_composite_hash,
ReplayDetector,
)
# Pre-trade safety gate with x402 attestation
def safe_trade_gate(mic: str, x402_txn_id: str) -> dict:
"""Returns attestation_ref for embedding in payment_required event."""
receipt = get_market_status(mic=mic)
ref = attestation_ref_from_receipt(receipt, x402_transaction_id=x402_txn_id)
if not is_market_open(ref):
raise ValueError(f"Market {mic} is {ref.status} — trade halted")
return ref.to_dict()
# Replay protection across a payment session
detector = ReplayDetector()
agent = Agent(
tools=[get_market_status, get_market_schedule, list_exchanges],
system_prompt=(
"You are a market-aware trading agent. "
"Before executing any trade, call get_market_status and verify the market is OPEN. "
"Treat HALTED and UNKNOWN as CLOSED — halt all execution."
),
)
Auto-Provisioning
On first tool call, the library automatically provisions a free sandbox key (25 calls/24h) from
Headless Oracle and saves it to ~/.headless_oracle/config.json. No signup required.
For higher limits, set HEADLESS_ORACLE_API_KEY in your environment or pass api_key= directly.
Supported Exchanges (28 total)
| MIC | Exchange | Type |
|---|---|---|
| XNYS | NYSE | Equities |
| XNAS | NASDAQ | Equities |
| XLON | London Stock Exchange | Equities |
| XJPX | Japan Exchange Group (Tokyo) | Equities |
| XPAR | Euronext Paris | Equities |
| XHKG | Hong Kong Exchanges | Equities |
| XSES | Singapore Exchange | Equities |
| XASX | Australian Securities Exchange | Equities |
| XBOM | BSE India | Equities |
| XNSE | NSE India | Equities |
| XSHG | Shanghai Stock Exchange | Equities |
| XSHE | Shenzhen Stock Exchange | Equities |
| XKRX | Korea Exchange | Equities |
| XJSE | Johannesburg Stock Exchange | Equities |
| XBSP | B3 Brazil | Equities |
| XSWX | SIX Swiss Exchange | Equities |
| XMIL | Borsa Italiana | Equities |
| XIST | Borsa Istanbul | Equities |
| XSAU | Saudi Exchange (Tadawul) | Equities |
| XDFM | Dubai Financial Market | Equities |
| XNZE | New Zealand Exchange | Equities |
| XHEL | Nasdaq Helsinki | Equities |
| XSTO | Nasdaq Stockholm | Equities |
| XCBT | CME (overnight Globex) | Derivatives |
| XNYM | NYMEX (overnight Globex) | Derivatives |
| XCBO | Cboe Options | Derivatives |
| XCOI | Coinbase | Crypto 24/7 |
| XBIN | Binance | Crypto 24/7 |
Links
Metadata
Release files for headless-oracle-strands 1.0.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 |
|---|---|---|---|---|
| headless_oracle_strands-1.0.0.tar.gz | 15.6 kB | Without provenance | Details for headless_oracle_strands-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| headless_oracle_strands-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for headless_oracle_strands-1.0.0-py3-none-any.whl |
Total release size: 27.2 kB
Release files / headless_oracle_strands-1.0.0.tar.gz
| Download URL | headless_oracle_strands-1.0.0.tar.gz |
|---|---|
| Size | 15.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2c4d9ab8aeafc16e29b21966700d4d2373bed434f404ff7bf85a66e80108f336
|
|
BLAKE2b-256 checksum How to use checksums |
259898b10d0e815cca14a65cf82d7e930266a92510eb23c8b3d3bafc1146449a
|
| 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_strands-1.0.0-py3-none-any.whl
| Download URL | headless_oracle_strands-1.0.0-py3-none-any.whl |
|---|---|
| Size | 11.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a53f1b99b6498115ae068162661f49564e348f494a421e66e2ba5b053ed04ce7
|
|
BLAKE2b-256 checksum How to use checksums |
e3641f6a0dc746a78162bc58391391648b57662cd6f218b2722213d3fd7fce10
|
| 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-strands 1.0.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.