Metadata-Version: 2.4
Name: graduate-oracle
Version: 0.1.0
Summary: Official Python SDK for the Graduate Oracle API — calibrated pump.fun probability scores, runner odds, creator history, smart-money positioning.
Author-email: Graduate Oracle <hello@graduateoracle.fun>
License: MIT
Project-URL: Homepage, https://graduateoracle.fun
Project-URL: Documentation, https://graduateoracle.fun/docs
Project-URL: Repository, https://github.com/Dspro-fart/graduate-oracle
Keywords: pump.fun,solana,memecoin,trading,api,oracle,calibration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Office/Business :: Financial :: Investment
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28

# graduate-oracle

Official Python SDK for the [Graduate Oracle API](https://graduateoracle.fun) — calibrated pump.fun probability scores, runner odds, creator history, smart-money positioning, and forward-validated public accuracy receipts.

## Install

```bash
pip install graduate-oracle
```

## Quickstart

```python
from graduate_oracle import GradOracle

# Mint a free key (200 calls/day) — save the returned key, we don't store it
key = GradOracle.mint_free_key("you@example.com")

client = GradOracle(api_key=key)

# Score a single mint
mint = client.probe("7xqURv1Pf3KJU2GjNsdb3oBYesQ1ZknyDeSXWULGpump")
print(f"grad_prob: {mint['grad_prob']*100:.0f}%")
print(f"5x from now: {mint['runner_prob_5x_from_now']*100:.0f}%")
print(f"smart money in: {mint.get('smart_money_in', 0)}")

# Top runners ranked by from-now upside
top = client.runners(tier="5x", min_prob=0.20)
for m in top["mints"]:
    print(m["mint"], m["runner_prob_5x_from_now"])

# Mints with smart-money wallets currently in top buyers
active = client.smart_money_active(min_smart=2)
print(f"{active['count']} mints with 2+ smart wallets")

# Public calibration receipts (no auth needed)
acc = client.accuracy()
print(acc["self_correcting"], acc["drift"]["lifetime_rate"])
```

## API surface

Every method returns a `dict` parsed from JSON:

| Method | Endpoint | Description |
|---|---|---|
| `client.live()` | `GET /api/v1/live` | Full live universe, all signals |
| `client.probe(mint)` | `GET /api/v1/probe/{mint}` | Single mint, full enrichment |
| `client.runners(tier="5x")` | `GET /api/v1/runners` | Ranked by from-now upside |
| `client.smart_money_active()` | `GET /api/v1/smart_money_active` | Mints with leaderboard wallets in |
| `client.wallet(addr)` | `GET /api/v1/wallet/{addr}` | Wallet lifetime stats |
| `client.leaderboard(kind="smart")` | `GET /api/v1/wallets/leaderboard` | Top wallets |
| `client.stats()` | `GET /api/v1/stats` | Platform aggregates |
| `client.accuracy()` | `GET /api/accuracy` | Public calibration receipts |
| `client.health()` | `GET /health` | Liveness check |

## Errors

Any non-2xx raises `GradOracleError`:

```python
from graduate_oracle import GradOracle, GradOracleError

try:
    client.probe("invalid_mint")
except GradOracleError as e:
    print(e.status, e.body)   # e.g. 404, {'detail': {'error': '...'}}
```

The SDK auto-retries with backoff on `503` (cold-start / observer warming) and connection errors — up to 3 attempts.

## Pricing tiers

- **Free** — 200 calls/day, 5-min delayed live data
- **Builder** — 0.4 SOL/mo (~$80) — 5,000 calls/day, real-time, premium endpoints
- **Pro** — 1 SOL/mo (~$200) — 50,000 calls/day, webhooks
- **Enterprise** — websocket firehose, custom rate limits, white-label

See [graduateoracle.fun/api](https://graduateoracle.fun/api) for full pricing and the comparison table.

## License

MIT
