hodlodds-mcp

A local stdio MCP server for HodlOdds crash odds. Free tools explain token coverage, data markets and feed status. With a local wallet configured, paid tools use x402 USDC on Solana or Base with per-call and per-session spending limits. Paying on Base does not change the data universe: current paid scores cover active SOL-quoted pump.fun graduates.

Source: HodlOdds SDK and MCP public repository.

Install

pip install hodlodds-mcp
hodlodds-mcp
# Or run in an isolated environment:
uvx hodlodds-mcp

Python 3.11+ is required. Dependencies are hodlodds>=0.3.1,<0.4 and mcp>=2.3,<3. The HodlOdds client supplies its pinned x402 dependencies. This package starts a local process, not an HTTP MCP endpoint. Stdout is reserved for MCP protocol messages.

Tools and prices

last_known explicitly opts into the SDK's last() route. It can also be used while the feed is live. Its stale, freshness, age_s and horizon_remaining_s fields preserve the original forecast window; paying does not restart it. When stale, confidence is downgraded one level. The same per-call cap, session budget and uncertain-payment pause apply to all paid tools.

board accepts limit, sort, max_risk, min_risk, min_liquidity_sol, min_age_min, max_age_min, min_trades_5, min_confidence, include_crashed, mints, chain and platform. Sorts are lowest_risk (default), safest (an alias for lowest_risk), riskiest, liquidity, newest and active. Without mints, limits are 10–500 (default 50). With a watchlist of 1–100 distinct Solana mint addresses, the default limit is its length and explicit limits are 1–100. Only returned coins are charged. not_delivered contains coverage/filter facts for omitted mints, not inferred odds. Probability filters use 0–1; confidence is high, medium or low.

For lowest_risk/safest, omitted filters default server-side to min_trades_5=3 and include_crashed=false. Explicit values override them, including min_trades_5=0 and include_crashed=true. Watchlists get neither default: your crashed holdings stay visible and flagged unless explicitly filtered out. The offer binds the client's parameters without these defaults; the server applies them deterministically when selecting and pricing rows. Answers retain filters, defaults_applied and total_matches.

crash_odds, last_known, board and coverage accept optional chain and platform strings, comma-separated strings or lists. Currently use chain="solana" or its CAIP-2 ID and platform="pumpfun"; pump and pump.fun are aliases. Values are case-insensitive; empty, duplicate and unsupported values are refused before payment. Use markets() to check current availability. Data markets and payment networks are separate choices.

Every result includes “Odds, not guarantees. Not financial advice.” Errors have MCP isError: true, a structured error code and http_status when known. Recognized public server messages are exposed as server_error and server_code (such as offer_changed); arbitrary rejected content is not echoed. As in 0.1.0, confidence remains the level string: high, medium, low, or missing. The new confidence_detail field retains the full server object, including reasons and its band evidence (an empty object when absent). The row's band evidence also passes through. Model IDs/hashes, alert when supplied, already_crashed and note also pass through. Only undocumented row fields add an extra-fields warning. Receipts contain public payment details, not signed authorizations or key contents. Spending is tracked in integer atomic USDC; displayed USDC amounts are exact decimal strings.

Configuration

Tool arguments cannot change the wallet, recipient, payment network, endpoint or spending limits. Set these in the MCP process environment:

The default per-call cap can buy at most two delivered board rows. A larger offer is refused before key access; the cap does not trim an answer down to two coins. Set 0.50 explicitly for up to 100 delivered rows, for example. The accepted offer amount, not the requested limit, determines the budget debit.

Read-only mode: omit the key and session budget. The registered tools are status, markets, coverage and meaning. No key is loaded at startup in either mode. Key files must be regular, non-symlink files, mode 0600, at most 4 KiB. Solana uses solana-keygen JSON; Base uses a local hex/JSON private-key file. Use a dedicated low-balance wallet. Never put key contents in a client configuration.

Client configuration

Claude Desktop: merge this read-only setup into claude_desktop_config.json:

{
  "mcpServers": {
    "hodlodds": {
      "command": "uvx",
      "args": ["hodlodds-mcp"]
    }
  }
}

Use the executable's absolute path if the desktop app cannot find uvx. To enable payments, add the environment values below to that server entry. This is also a generic stdio process configuration for clients that accept command, args and env (adapt the surrounding configuration to your client):

{
  "command": "hodlodds-mcp",
  "args": [],
  "env": {
    "HODLODDS_BASE_URL": "https://api.hodlodds.com",
    "HODLODDS_NETWORK": "solana",
    "HODLODDS_PAY_TO": "REPLACE_WITH_VERIFIED_RECIPIENT_FROM_META",
    "HODLODDS_KEYPAIR": "/absolute/path/to/payer.json",
    "HODLODDS_MAX_PRICE_USDC": "0.01",
    "HODLODDS_SESSION_BUDGET_USDC": "0.10"
  }
}

Replace the recipient and file-path placeholders before starting. The example uses real mainnet USDC. For Base payments, choose base, its recipient and an EVM key file. Test networks require a test API that offers that network: use devnet or base-sepolia, test USDC and the matching verified recipient. These snippets are configuration templates; assistant applications were not launched during offline package testing.

Restart the MCP process after changing its environment. Reconcile any uncertain payment first: a restart also resets the session budget.

Payment safety and reconciliation

Paid calls are serialized across tools. The SDK validates the offer's network, asset, pinned recipient, query binding and amount before key access or signing. The session budget checks that exact accepted amount, then reserves it before the authorized request. A successful receipt retains the debit. Exhausting the budget refuses the next payment before signing; free tools remain available.

A refusal marked HodlOdds-Charged: no is free only when the receipt does not indicate success or a transaction. A conflicting or malformed receipt remains uncertain. Confirmed free refusals refund the reservation, return an error and leave payments enabled.

For a board 409 with code: "offer_changed", the SDK can request a new offer once before signing only, with the same query and repeated price and budget checks. A signed request is never retried automatically. After signing, a 409 with code: "offer_changed" and HodlOdds-Charged: no (without a conflicting receipt) means nothing was charged, but the client must call again; the SDK never re-signs on its own. A second automatic authorization could be settled twice if a server misbehaved. The free refusal releases the budget reservation.

After an uncertain payment—such as a lost response, missing receipt or conflicting receipt—all further paid calls pause. The reserved amount stays spent until the operator reconciles it against finalized wallet history and payment records. The result includes public reconciliation details. There is no tool to clear the pause, no automatic retry or redemption, and no pending authorization file is written. Restart only after reconciliation and choose a new budget that accounts for prior spending.

The budget is local to one process and is not shared or persistent. Every restart resets it. The paid request timeout is 90 seconds. Cancellation does not abandon in-flight payment accounting. A settled answer with an unexpected shape returns raw data with a warning instead of authorizing another payment. Receipts report server settlement; they are not independent proof of finality.

Meaning and freshness

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.

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 crash is a completed one-minute close in SOL at least 90% below the reference price within the displayed 60-minute window. as_of and horizon_end are UTC Unix seconds. Confidence describes historical calibration and evidence; it is not a token-specific interval or guarantee. Missing odds, missing confidence, stale data and uncovered tokens are not safety signals. Very low odds say “under 0.1%”, never a rounded zero.

dd_60 is close divided by the maximum close in the previous 60 minutes, minus one. Zero is the hour's high. At -0.90 or lower, already_crashed is true and the row's note and summary warn that little may be left to fall. Unknown drawdown gives a null flag. This is a past-price fact, not a new model prediction. Below about 2%, historical crash rates have run up to about twice the predicted value, under one percentage point in absolute terms; those answers carry low confidence.

Odds, not guarantees. Not financial advice.

Development

From the public repository root, with the dependencies and pytest installed:

python -m pytest -q mcp/tests
python -m build mcp

Tests use this checkout's SDK and MCP sources, mocked HTTP and signing, and an in-memory MCP session. Socket connections and DNS lookups are disabled. They do not prove live settlement or desktop-client integration. The budget adapter uses the SDK's watch accounting hook, so the dependency is bounded to hodlodds>=0.3.1,<0.4 and tested before upgrades.

server.json contains registry metadata for com.hodlodds/hodlodds-mcp. Publishing to PyPI and publishing a registry listing are separate steps; namespace ownership and registry acceptance must be verified by the publisher.