Hodlodds MCP

hodlodds — Python client

Pay-per-answer crash odds for Solana memecoins, paid per request with x402 (USDC on Solana or Base). No accounts, no API keys.

The API at https://api.hodlodds.com accepts payments. Check its free status, markets and coverage endpoints before paying. Local test servers can use Solana devnet or Base Sepolia.

What it answers

What are the odds that this token's price falls 90% or more within the next 60 minutes?

0.04 is an estimated 4% chance of the defined event within the forecast window. Confidence describes historical calibration in that probability range, not a guarantee for this token. Higher means riskier, but a low number is not a safety signal: smaller or slower drops are not counted, and odds change minute by minute.

A crash is a completed one-minute close, priced in SOL, at least 90% below the reference price within the next 60 minutes. Coverage: SOL-quoted pump.fun graduates. Every answer carries a confidence level (high / medium / low) based on how well past predictions in that probability range matched reality.

dd_60 is the latest close divided by the maximum close in the previous 60 minutes, minus one. Zero means the token is at that hour's high; dd_60 <= -0.90 means it has already fallen at least 90% within the hour. Rows expose already_crashed (true, false, or null when the drawdown is unknown); an older collapse reads false. crashed_within_24h and last_crash_as_of say whether an API snapshot saw dd_60 <= -0.90 for the token within the last 24 hours, and the latest such snapshot time (UTC epoch seconds). The memory only knows snapshots the API received: a crash that happened entirely during an API outage is not seen. Both fields are null while the memory cannot vouch for the whole 24 hours: for 23 hours after a snapshot arrives more than an hour after the last one the memory recorded (a feed outage, or a replaced or restored memory file), after it exceeded its size limit (until the tokens it dropped would have expired), and while its store is failing. A new deployment starts with the memory available. Either crash flag adds a note and crash context in summary: a low crash probability after a collapse is not a recovery or safety signal. Below about 2%, observed crash rates have run up to about twice the predicted value, under one percentage point in absolute terms. Answers from 0.5% to 2% carry confidence: low; answers below 0.5% carry at most medium, with direction: historically under-predicted.

The normal risk and board routes charge only for fresh, covered answers. The opt-in /last route can charge for clearly labelled last-known odds within its 30-minute limit. Uncovered and ineligible answers are free. A refusal carrying HodlOdds-Charged: no is treated as free unless a successful payment receipt contradicts it; this includes an oversized-header 431. If eligibility changes after signing, that free refusal creates no pending payment.

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.

The opt-in /v1/risk/{mint}/last route returns stored odds at most 30 minutes after issuance, including exactly 1800 seconds. It also works while live. When stale, confidence drops high to medium or medium to low; low stays low and missing confidence stays missing. Its original horizon and expiry stay unchanged.

Install

pip install hodlodds                                        # from PyPI

pip install "git+https://github.com/hodlodds/hodlodds-sdk" # or the latest main

Python 3.10+. Dependencies: httpx, certifi>=2026.10.19 and the official x402[svm,evm]==2.25.0 SDK (pinned).

MCP server

The separate hodlodds-mcp package provides local stdio tools for market discovery and crash odds, with per-call and session payment limits.

pip install hodlodds-mcp See the MCP README for client configuration and payment safety.

Use

Command line:

hodlodds status

hodlodds markets hodlodds coverage --chain solana --platform pumpfun hodlodds risk --keypair ~/.config/hodlodds/wallet.json --pay-to --network solana hodlodds risk --keypair ~/.config/hodlodds/base-wallet.json --pay-to --network base hodlodds board --limit 100 --sort lowest_risk --max-risk 0.05 --min-liquidity 50 --max-price 0.5 \ --keypair ... --pay-to ... --network solana hodlodds last --keypair ... --pay-to ... --network solana

Python:

from hodlodds import HodlOdds, HodlOddsError

with HodlOdds("https://api.hodlodds.com", keypair="~/.config/hodlodds/wallet.json", network="solana", pay_to=" ", max_price_usdc="0.01") as client: print(client.status()["state"]) print(client.markets()) print(client.coverage(" ", chain="solana", platform="pumpfun")) try: answer = client.risk(" ") row = answer.data["row"] print(row["p_crash_60m"], row"confidence", answer.payment["explorer"]) except HodlOddsError as e: print(e, e.status, e.body)

e.payment["charged"] == False means a confirmed free refusal.

A PendingPayment needs reconciliation or explicit redemption.

is the payment address for your chosen payment network, published in GET /v1/meta. Verify and pin it in your code: the client refuses any offer that pays someone else.

Networks: devnet and solana (mainnet; mainnet is an alias) take a Solana JSON key file; base-sepolia and base take an EVM key file ({"private_key": "0x..."}, mode 0600). Prices are the same on both chains, and the API offers both; the client signs only on the network you chose.

base = HodlOdds("https://api.hodlodds.com", keypair="~/.config/hodlodds/base-wallet.json",

network="base", pay_to=" ", max_price_usdc="0.01")

Board options: limit 10–500 (default 50); sort = lowest_risk (default), riskiest, liquidity, newest, active; filters max_risk, min_risk, min_liquidity_sol, min_age_min, max_age_min, min_trades_5, min_confidence (high/medium/low) and include_crashed (True/False). The total price is 0.005 × coins returned; pass max_price_usdc in Python or --max-price on the CLI at least that high. The default per-call maximum is 0.01 USDC, so boards normally need an explicit higher limit. The hard cap is 2.5 USDC for board calls only and 1 USDC for individual risk/last calls. Above your limit the client raises PriceLimitError (a HodlOddsError) before signing; its price_atomic and limit_atomic give the offered total and your limit in USDC atomic units (1 USDC = 1,000,000). min_trades_5 accepts integers from 0 through 9223372036854775807.

Compatibility: the 0.2.0 safest sort remains accepted as an alias for lowest_risk, and the mainnet payment-network alias still means solana. These older spellings are deprecated in examples; existing calls keep working.

For lowest_risk and its safest alias, the server applies min_trades_5=3, min_liquidity_sol=5 and include_crashed=false when those filters are omitted, so barely traded, illiquid or recently collapsed tokens do not dominate the list. The crash filter excludes both already_crashed and crashed_within_24h rows. Explicit values override the defaults, including min_trades_5=0, min_liquidity_sol=0 and include_crashed=True (CLI: --min-trades 0 --min-liquidity 0 --include-crashed). Other sorts keep their existing selection. An explicit mints= watchlist gets none of these defaults: crashed holdings remain visible and flagged unless you explicitly request include_crashed=False.

The lowest odds are usually the least-traded tokens; the default filters remove most inactive or recently collapsed tokens, not all.

Board answers return effective filters, defaults_applied (empty when no default was added) and excluded_by_defaults, the number of rows removed only by those defaults before the limit. The 402 offer body also shows defaults_applied and excluded_by_defaults; they are not part of the signed offer. If the API's recent-crash memory is unavailable, the defaults reason says so and the crash filter uses only already_crashed. The offer binds exactly the client's own normalized parameters. The server applies its documented defaults deterministically when selecting and pricing rows; the client does not add those defaults to the signed query.

board = client.board(limit=100, sort="lowest_risk", max_risk=0.05, min_liquidity_sol=50, max_price_usdc="0.5")

for row in board.data["rows"]: print(row["mint"], row["p_crash_60m"], row"confidence")

Explicitly include quiet and already-collapsed tokens:

all_rows = client.board(min_trades_5=0, include_crashed=True, max_price_usdc="0.25")

The cheaper, opt-in answer preserves its original horizon and labels its age:

last_known = client.last(" ") print(last_known.data["age_s"], last_known.data["freshness"])

last() costs 0.002 USDC and can return last-known odds up to 30 minutes old, including while the feed is live. Check stale, age_s, freshness and horizon_remaining_s; buying the answer does not renew its forecast.

When a board offer changes

A board 409 with code: "offer_changed" means the matching set changed between the offer and the paid request; the server marks that refusal HodlOdds-Charged: no. On the current API this 409 is returned only to a signed request, and a signed request is never retried automatically. With HodlOdds-Charged: no and no conflicting receipt, nothing was charged, but the client must call again; the SDK never re-signs on its own. In practice board() raises HodlOddsError with error.payment["charged"] == False; call board() again to get a new offer. A second automatic authorization could be settled twice if a server misbehaved. Watch loops treat a confirmed free refusal as a skip and continue on their next scheduled cycle. Uncertain payments stop the watch and require reconciliation.

As a safeguard only, SDK 0.3.1 and later request a new offer once only if the 409 occurs before signing, with no successful or uncertain receipt. That refresh uses the same query, repeats all price and budget checks, and signs and spends nothing.

Watchlists and market filters

Pass mints=[mint_a, mint_b] to restrict a board to 1–100 distinct Solana mint addresses. Duplicates are rejected locally before any request (and are a