graduate-oracle 0.1.0

Official Python SDK for the Graduate Oracle API — calibrated pump.fun probability scores, runner odds, creator history, smart-money positioning.

graduate-oracle

Official Python SDK for the Graduate Oracle API — calibrated pump.fun probability scores, runner odds, creator history, smart-money positioning, and forward-validated public accuracy receipts.

Install

pip install graduate-oracle

Quickstart

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("[e-mail]")

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:

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 for full pricing and the comparison table.

License

MIT