Metadata-Version: 2.4
Name: headless-oracle-crewai
Version: 1.0.1
Summary: CrewAI tools for Headless Oracle market state verification. SMA = Signed Market Attestation (not Simple Moving Average).
License: MIT
Keywords: headless-oracle,crewai,market-data,trading,agents,mcp
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: crewai
Requires-Dist: crewai>=0.1; extra == "crewai"

# headless-oracle-crewai

CrewAI tools for [Headless Oracle](https://headlessoracle.com) market state verification.

**Note: SMA in this package denotes "Signed Market Attestation" — not Simple Moving Average.**

```bash
pip install headless-oracle-crewai
```

## Usage

```python
from headless_oracle_crewai import MarketStatusTool, MarketScheduleTool

# Zero config — auto-provisions sandbox key on first tool call
tools = [MarketStatusTool(), MarketScheduleTool()]

# Use with CrewAI agent
from crewai import Agent, Task, Crew

trader = Agent(
    role="Market-Safe Trader",
    goal="Only execute trades when markets are verified OPEN",
    tools=tools,
)
```

## Tools

### MarketStatusTool
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

### MarketScheduleTool
Returns upcoming open/close times in UTC. DST-aware via IANA timezone identifiers.

## Auto-provisioning

On first tool call, the library automatically provisions a free sandbox key (100 calls/24h) from Headless Oracle and saves it to `~/.headless_oracle/config.json`. No signup required.

## Supported Exchanges

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

- [Docs](https://headlessoracle.com/docs)
- [SMA Protocol RFC-001](https://headlessoracle.com/docs/sma-protocol/rfc-001)
- [CrewAI Integration Guide](https://headlessoracle.com/docs/integrations/crewai)
