Metadata-Version: 2.4
Name: markovian
Version: 1.0.0
Summary: Python SDK for the Markovian Protocol: verifiable market-regime data, on-chain ZK proofs, and STAMP commitment from a proof-of-intelligence Layer 1.
Author-email: Markovian Protocol <hello@quantsynth.net>
License: MIT
Project-URL: Homepage, https://markovianprotocol.com
Project-URL: Documentation, https://markovianprotocol.com/build
Project-URL: Source, https://github.com/MarkovianProtocol/markovian-protocol
Project-URL: Explorer, https://chain.quantsynth.net
Keywords: markovian,oracle,zk,zero-knowledge,blockchain,market-regime,defi,prediction-markets,markov,provenance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
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 :: Investment
Classifier: Topic :: Security :: Cryptography
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.25
Requires-Dist: numpy>=1.20
Requires-Dist: py_ecc>=6.0
Dynamic: license-file

# markovian

Python SDK for the [Markovian Protocol](https://markovianprotocol.com), a proof-of-intelligence Layer 1 that produces ZK-verified market-regime classifications and commits arbitrary data to an immutable, Bitcoin-anchored chain.

```bash
pip install markovian
```

## Why it exists

More than $400M has been lost to oracle manipulation since 2022. Every exploit shared a root cause: an external price feed that could be skewed. The Markovian Protocol removes the feed. Each block is a Markov state transition, `s_N = M^N x s`, where `M` is the protocol-published transition matrix and `s` derives deterministically from the previous block hash. A BN128 zero-knowledge proof attesting to that computation is verified on-chain, so the output (a regime classification of ACCUMULATION, MARKUP, or DISTRIBUTION) is reproducible and cannot be forged by any single party.

This package is the client for reading that data, verifying the proofs locally, and committing records to the chain.

## Quickstart

The free tier is keyless. No account, no API key.

```python
from markovian import MarkovianClient

client = MarkovianClient()

# Latest ZK-proven regime snapshot for liquid tickers
for r in client.latest():
    print(f"{r.ticker:<6} {r.regime:<14} {r.confidence*100:.1f}%")

# QQQ    DISTRIBUTION   61.3%
# SPY    DISTRIBUTION   67.8%
# GLD    DISTRIBUTION   99.0%

# Regime history for a single ticker
history = client.regime("QQQ", days=90)

# Snapshot across several tickers at once
snap = client.batch(["SPY", "QQQ", "GLD", "TLT"])
```

From the command line:

```bash
markovian latest
markovian regime QQQ 90
markovian tip
```

## Verify a proof locally

Verification requires no trust in the API. The ZK circuit runs client-side against a Merkle root.

```python
result = client.verify(merkle_root, local=True)
print(result["verified"], result.get("local_zk_verified"))
```

## Commit data to the chain (STAMP)

STAMP writes any JSON-serialisable record to the chain permanently. The result is unforgeable, publicly verifiable, and Bitcoin-anchored.

```python
client.faucet("my-wallet")                      # 100 free test MKV
proof = client.stamp({"event": "audit-2026"}, wallet="my-wallet")
print(proof["verify_url"])
```

## Tiers

| Tier       | Access                                  | Key |
|------------|-----------------------------------------|-----|
| Free       | Liquid tickers, 90-day window           | None |
| Pro        | All tickers, full history, CSV export   | Required |
| Enterprise | All of Pro, plus inline ZK proofs       | Required |

Keys are issued at [markovianprotocol.com](https://markovianprotocol.com).

## API surface

- `latest()` — current regime snapshot for liquid tickers
- `regime(ticker, days)` — regime history for one ticker
- `batch(tickers)` — snapshot across multiple tickers
- `catalog()` — available tickers and coverage
- `verify(merkle_root, local)` — verify a proof against the registry, optionally re-running the ZK circuit locally
- `stamp(data, wallet)` — commit a record to the chain
- `faucet(wallet)` — claim test MKV
- `watch(tickers, callback)` — poll for regime transitions
- `tip()`, `block(height)`, `ledger()` — chain primitives

## Requirements

Python 3.8+, with `requests`, `numpy`, and `py_ecc` (installed automatically).

## Links

- Protocol: https://markovianprotocol.com
- Build docs: https://markovianprotocol.com/build
- Explorer: https://chain.quantsynth.net
- Source: https://github.com/MarkovianProtocol/markovian-protocol

MIT licensed.
