headless-oracle-strands 1.0.0

Strands Agents SDK tools for Headless Oracle market state verification. SMA = Signed Market Attestation (not Simple Moving Average).

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, or UNKNOWN
• Fail-closed: UNKNOWN and HALTED MUST be treated as CLOSED
• 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

• Headless Oracle Docs
• x402 Payment Guide
• SMA Protocol RFC-001
• AWS AgentCore x402 Sample