how to use it

Build on calibrated graduation predictions.

One signal. One endpoint. Every prediction logged before the outcome and resolved against on-chain truth.

58% of high-confidence calls actually graduate

Forward predictions resolved against on-chain truth — every one hashed before its outcome. ≥70% confidence band: 58% graduated (n=2,400+). The honest number, not a backtest headline. Verify any prediction at /receipts.

Quick start

Three steps. Two endpoints.

Get a key

# Free key: 200 calls/day, 5-min delayed data
curl -X POST https://graduateoracle.fun/api/keys/new \
  -H 'Content-Type: application/json' \
  -d '{"email":"you@example.com"}'

Read the live firehose

curl https://graduateoracle.fun/api/v1/live \
  -H 'Authorization: Bearer grad_...'

Returns every currently-tracked mint with calibrated grad_prob, entry_mult, age, and supporting context. Updates every ~2 seconds.

Filter for actionable signals

curl https://graduateoracle.fun/api/v1/live \
  -H 'Authorization: Bearer grad_...' \
  | jq '.mints[] | select(.grad_prob >= 0.70 and .current_mult <= 2.0)'

That's the same gate the TG bot fires on. ≥70% grad_prob with clean entry — 58% forward, on-chain-resolved hit rate at ≥70% (n=2,400+) — resolved against truth, not a backtest.

Pricing

Tier	Calls/day	Data freshness	Webhooks	Price
Free	200	5-min delayed	—	$0
Builder	5,000	real-time	—	0.5 SOL/mo
Pro	50,000	real-time	✓	1.5 SOL/mo

Pricing in SOL, paid on-chain via the /upgrade flow. See pricing →

Authentication

All /api/v1/* endpoints require a bearer token.

Authorization: Bearer grad_xxxxxxxxxxxx

Or via X-API-Key header. Keys are bearer credentials — treat them like passwords.

Reference

Endpoint	What it returns
`GET /api/v1/signals`	Cursor-paginated cross stream — the machine-consumable feed (poll, zero-miss, resumable)
`GET /api/v1/live`	Every tracked mint, scored
`GET /api/v1/probe/{mint}`	Single mint, full breakdown
`GET /api/predictions/by_mint/{mint}`	All historical predictions for a mint (receipts)
`GET /api/ledger/commits`	Hourly Merkle commits — verify a prediction was logged before its outcome
`GET /api/ledger/proof/{prediction_id}`	Cryptographic proof of a single prediction's commit
`GET /api/accuracy`	Live calibration receipts (LOO + forward)
`GET /api/scope`	What we predict, calibration bands, label sources

Full schema reference: Swagger UI ↗ · OpenAPI spec ↗

Signals stream

The machine-consumable feed. GET /api/v1/signals returns composite-receipts crossings in the order they became deliverable. Poll with the cursor from the prior response as since — zero missed crossings, zero duplicates, fully resumable after a crash. Built for execution bots, not dashboards.

curl https://graduateoracle.fun/api/v1/signals?since=<cursor> \
  -H "Authorization: Bearer $KEY"

→ { "count", "cursor", "signals": [ {
      "mint", "tier", "composite_score", "score_ratio",
      "smart_money_in", "max_mult_at_cross", "age_s_at_cross",
      "mc_at_cross_usd", "cross_at", "delivered_at" } ] }

Filter by tier: ?tier=ACT / WATCH / SCOUT / all. Webhook push (HMAC-signed POST on every cross) available via POST /api/v1/webhooks.

Tier semantics

Tier	Gate	What it means
`⚡ ACT`	model confidence ≥ 0.15	Highest conviction. Trust-it band.
`📊 WATCH`	0.05–0.15	Mid conviction.
`🛰 SCOUT`	0.02–0.05, or strong composite	Recall tier — surfaced so it isn't missed; you judge it.

Honest status: the 3-tier structure shipped 2026-05-16 and is forward-validating in public right now. Per-tier hit rates are back-test projections under live verification — not yet proven forward numbers. We publish the verdict (whichever way it breaks) on the receipts trail when the pre-registered sample floor is hit. We don't quote a rate we haven't earned forward. Pilot phase — no pricing on this feed yet, deliberately, until the numbers are real.

Errors

All errors are JSON with the same shape:

{
  "detail": {
    "error":   "rate_limit_exceeded",
    "message": "Daily quota of 200 reached. Resets at 1777502400.",
    "hint":    "/upgrade for higher limits"
  }
}

Status	Error	Meaning
401	`invalid_or_expired_key`	Auth header missing/wrong
429	`rate_limit_exceeded`	Daily quota hit
503	`no_snapshot`	Observer warming up — retry in seconds

Try the TG bot → See the receipts Verify a prediction

NFA · DYOR · prediction model output, not financial advice · @GraduateOracle