Metadata-Version: 2.4
Name: marketschema
Version: 1.1.0
Summary: Python SDK for the MarketSchema Public API v1
Home-page: https://github.com/FlyingMobula5/MarketSchema
Author: MarketSchema
Author-email: api@marketschema.com
Project-URL: Documentation, https://marketschema.com/docs
Project-URL: Public API, https://marketschema.com/docs/api
Project-URL: Source, https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# MarketSchema Python SDK

Official Python client for the [MarketSchema](https://marketschema.com) Public API v1 —
structural market intelligence: schema scores, market-risk gauges, proprietary indexes,
narratives, and themes, built for both humans and trading agents.

## Install

```bash
pip install marketschema
```

## Quickstart

```python
from marketschema import MarketSchemaClient

client = MarketSchemaClient(api_key="ms_...")  # mint a free key at marketschema.com/account/api-keys

# Who am I / what can my key do?
print(client.whoami())
print(client.capabilities())

# Single-asset intelligence packet
nvda = client.asset("NVDA")
print(nvda["schema_score"], nvda["regime_label"])

# Batch check (paid tiers)
result = client.batch(["NVDA", "MSFT", "SPY"])

# Server-sent event stream of live updates
for event in client.stream():
    print(event)
```

## Agent / bot endpoints

The SDK speaks the full bot contract — registration, heartbeats, snapshots,
webhooks, and the paper/replay/shadow harnesses:

```python
client.register(name="my-bot", environment="paper")
client.heartbeat(status="ok")
client.webhook_register(url="https://example.com/hook", events=["score.changed"])
```

Complete, runnable agents live in
[`examples/`](https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python/examples)
(`paper_bot.py`, `replay_bot.py`, `shadow_bot.py`).

## Auth, limits, errors

- Auth is a single `X-API-Key` header — the client sets it for you.
- Free tier: 1 key, 60 requests/min. Paid tiers raise key counts, rate
  limits, and batch quotas — see [marketschema.com/pricing](https://marketschema.com/pricing).
- Non-2xx responses raise `MarketSchemaError` with `.status_code` and the
  parsed error envelope on `.response`.

## Links

- Docs: https://marketschema.com/docs
- API reference: https://marketschema.com/docs/api
- Source: https://github.com/FlyingMobula5/MarketSchema/tree/main/sdk/python

MIT licensed.
