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)

Links

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