# HodlOdds

0.04 means about 4 in 100 tokens like this one lose 90% or more of their price within the next 60 minutes. Higher means riskier, but a low number does not mean safe: smaller or slower drops are not counted, and the odds change minute by minute.

## How to explain a score to a person

- Read `p_crash_60m` as "X% chance this token falls 90% or more within the next 60 minutes (about N in 100)"; X and N are 100 times the score. The window starts at `as_of`, not the request time.
- Higher = riskier. Use it to avoid or exit risky tokens, never as a reason to buy or hold.
- Never call a token "safe" because its odds are low; smaller drops (for example −50%) and slower declines are not covered.
- A score is valid only until the next minute's update. Re-request immediately before acting; never reuse an older score. For continuous monitoring, request once per minute; `/v1/board` returns many tokens in one paid call.
- Always state the confidence level (high/medium/low), or say when it is missing. A missing score, an uncovered token or `stale` data is not a safety signal.
- Odds, not guarantees. Not financial advice.

## Freshness

Scores are recomputed every 60 seconds, about 20 seconds after each minute closes, from completed one-minute bars up to `as_of`. Each score covers the 60 minutes after its `as_of` time and is valid only until the next update; the odds for the same token can rise sharply from one minute to the next. Scoring starts around :20; computation and publication can delay availability. For decisions, refresh immediately before acting and once per minute for continuous monitoring, checking `as_of` for a new minute. The API freshness cutoff is separate: by default, data becomes `stale` more than 120 seconds after `issued_at` or after `expires_at`. A new request does not restart the forecast window.

> A paid x402 v2 API for 60-minute crash odds on covered, active SOL-quoted pump.fun graduates. Data, not advice. Paid access is open only while `/v1/meta` reports `public_beta: true`; a live feed alone does not mean paid access is enabled.

A crash is a completed one-minute close in SOL at least 90% below the reference price within the displayed 60-minute window. The forecast ends at `horizon_end`; requesting it later does not start a new hour. This is not a measure of sellability, every kind of loss, or temporary intraminute price drops. Losses can occur without warning.

## Start here

- [API docs](https://api.hodlodds.com/docs): Python quickstart, an explicitly unverified-offline TypeScript example, payment policy and response semantics.
- [OpenAPI 3.1](https://api.hodlodds.com/static/openapi.json): routes, schemas and clearly illustrative response examples.
- [Free status](https://api.hodlodds.com/v1/status): live/stale/down feed, issuance age, incidents and observed uptime.
- [Free metadata](https://api.hodlodds.com/v1/meta): coverage, model hashes, current prices, accepted payment networks/assets/recipients, confidence evidence and beta/payment readiness.
- [Terms of Use](https://api.hodlodds.com/terms): refused requests are free; a lost paid answer can be redeemed once; not financial advice.
- [Privacy](https://api.hodlodds.com/privacy): no accounts, cookies, trackers or access logs; payment rows 90 days.

## Paid routes

- GET `/v1/risk/{mint}`: one covered SOL token; default $0.01 USDC.
- GET `/v1/risk/{mint}/last`: explicit opt-in last-known odds from the latest stored snapshot; default $0.002 USDC (2,000 atomic units). Available only when `now - issued_at <= 1800` seconds, including exactly 1800. It also works while the feed is live, at the same lower price; then the odds equal the fresh route's odds but still carry last-known fields. There is no `/v1/board/last`.
- GET `/v1/board?limit=50&sort=safest&min_liquidity_sol=50&max_age_min=1440`: one current fresh board, no pagination or cursors. `limit` is 10..500 (default 50); fewer matching coins may be returned. Each delivered coin costs $0.005 USDC (5,000 atomic units): 37 matches with limit 100 costs $0.185; 500 cost $2.50. Zero matches return free 200 with empty rows and no payment headers. Sort identifiers: `safest` — lowest predicted odds first (a ranking, not a safety claim). Default: `safest`. Other sorts: `riskiest`, `liquidity`, `newest`, `active`; ties use mint ascending. Filters: `max_risk`/`min_risk` in [0,1], nonnegative `min_liquidity_sol`, `min_age_min`/`max_age_min`, nonnegative integer `min_trades_5`, and `min_confidence=high|medium|low`. Null values never pass numeric filters; missing confidence never passes a confidence filter. Liquidity is quote-side SOL reserve, not executable sell depth. A paid retry re-evaluates the current fresh snapshot and delivers exactly the priced count if enough matches remain; otherwise free 409 `matches changed; request again`, with no settlement. The normalized query and count must match the requirement. Rows may change between challenge and delivery; stale data returns free 503. The server rechecks before settlement.

Normal risk and board routes stay fresh or free. The separate last-known route can charge for explicitly labelled older SOL odds within its 30-minute limit; they are never sold as fresh. All eligibility checks run before payment and again before settlement. Payment uses the official x402 v2 `exact` client and authorization flow. When configured, Solana and Base are alternative payment networks at the same USDC prices; they buy the same covered SOL-token data. This never expands non-SOL model coverage. Base uses EIP-3009 authorization, with no approval transaction or SPL Memo. Read the accepted options in `/v1/meta` and the current challenge; select one explicitly. Test modes use Solana devnet or Base Sepolia USDC, never mainnet funds. The unpaid eligible request returns 402 with `PAYMENT-REQUIRED`; the client signs locally and retries with `PAYMENT-SIGNATURE`. A settled answer carries `PAYMENT-RESPONSE`. Independently approve the recipient, network, USDC mint/contract and maximum amount before signing. Never provide a private key to HodlOdds.

403 or a Cloudflare Access login response before launch is infrastructure access control, not a payment requirement. 503 means a stale/down feed on fresh-only routes, no stored snapshot, beta disabled or service unavailable. A fresh risk 503 can include `hint: /v1/risk/{mint}/last` and `last_known_age_s` when eligible: never follow it as an automatic paid fallback. 410 on the last-known route means `Last known odds too old`, with `age_s` and `as_of`; no payment settles. 404 means unknown, uncovered or experimental non-SOL. Empty boards return free 200. Non-SOL rankings, if included in the 404, are free, not validated probabilities; mid-range scores historically underpredicted incidence. 400 rejects unknown/invalid board parameters, including limits outside 10..500; 422 rejects malformed route inputs; 429 includes Retry-After. These refused answers do not settle new payments. 409 rejects board match/offer changes without settlement, or a replayed signed payment whose original may already have settled. A 402 after payment or a connection failure can be ambiguous: preserve the receipt/transaction and reconcile on-chain before signing another payment. Do not automatically retry paid requests.

## Settlement recovery

Keep an ambiguous attempt's identical PAYMENT-SIGNATURE private. The server reconciles
on-chain evidence in the background. Resend to the same route and normalized board query:
409 with Retry-After means pending verification; final not_settled returns free 409 and
requires a new offer. A settled_onchain undelivered payment can be redeemed once within
24 hours of original verification for the current eligible answer, without a second
settlement. Success carries HodlOdds-Redeemed: <tx>. Stale/uncovered answers and boards
with fewer than the original priced_n are refused free, preserving the redeem until expiry.
Use HodlOdds-Redeem: 1 to require recovery only (unknown claims are refused, never settled).
The Python SDK retains HodlOddsError.payment privately and exposes client.redeem(payment).
CLI ambiguous failures save a 0600 file under ~/.config/hodlodds/pending/; explicitly run
hodlodds redeem <file>. Never log or share that file or signature. Try after ~2 minutes;
confirmation can take longer. Neither SDK nor CLI automatically redeems or signs again.

## Interpreting an answer

Boards use `hodlodds.board.v1`: `rows`, normalized `sort` and `filters`, requested `limit`, `returned`, `total_matches`, `price_usdc`, `unit_price_usdc` and the shared forecast timestamps/model fields. `/v1/meta` publishes `payments.prices.board` as `{unit_price_usdc: "0.005", min_limit: 10, max_limit: 500, default_limit: 50}`. Approve the dynamic total, not the unit price.

`p_crash_60m` is a decimal probability. Historical bands and the optional `confidence` object summarize already-seen historical weekly BF refits, not independent validation of this frozen serving fit. High/medium/low is an ordinal calibration/evidence label, not a token-specific statistical interval or a guarantee. Band counts are dependent landmarks, not distinct mints. Legacy snapshots may lack confidence. Non-SOL confidence is always experimental. Lower odds do not remove the possibility of a loss.

`as_of`, `issued_at`, `expires_at` and `horizon_end` are UTC Unix seconds. Honor expiry, coverage and model versions. An alert field is published only if separately authorized; do not infer alerts from its absence. Historical ranking improves only modestly over simple baselines; a trading benefit has not been demonstrated.

Last-known answers add `stale`, `age_s`, `freshness: live|stale` and `horizon_remaining_s = max(0, horizon_end - now)`. `horizon_end` stays `as_of + 3600`; `expires_at` is the original fresh expiry, not renewed by the request. When stale, confidence drops one level (high to medium, medium to low, low stays low), adding `stale data: N min old` with whole elapsed minutes. Experimental stays experimental and is never a paid answer; absent legacy confidence stays absent. The probability and historical evidence never change. Do not treat an old forecast as a new forecast or as current odds.

The operator runs an independent trading strategy that may hold these tokens. It receives no customer API purchases, searches or order flow. Payment never changes a score.

Crash = price falls 90% or more within 60 minutes. Odds, not guarantees. Not financial advice.