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

# headless-oracle-langchain

LangChain 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-langchain
```

## Usage

```python
from headless_oracle_langchain import MarketStatusTool, MarketScheduleTool

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

# Use with LangChain agent
from langchain.agents import AgentExecutor, create_tool_calling_agent
```

## 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)
- [LangChain Integration Guide](https://headlessoracle.com/docs/integrations/langchain)
