hodlodds-sdk

# hodlodds — Python client

Pay-per-answer **crash odds for Solana memecoins**, paid per request with
[x402](https://www.x402.org) (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 is unavailable. 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; those answers carry
`confidence: low`.

| Route | Price | Notes |
|---|---|---|
| `GET /v1/status` | free | Feed state (`live` / `stale` / `down`), age, incidents, uptime |
| `GET /v1/meta` | free | Definition, prices, payment details, model card |
| `GET /v1/markets` | free | Available data chains, platforms and coverage |
| `GET /v1/coverage/{mint}` | free | Coverage stage and reason for one token |
| `GET /v1/risk/{mint}` | $0.01 | Fresh odds for one token |
| `GET /v1/board?limit=N` | $0.005 per coin delivered | Request 10–500 coins, or a watchlist of 1–100 distinct mints; pay only for coins returned, empty is free |
| `GET /v1/risk/{mint}/last` | $0.002 | Last known odds, at most 30 minutes old (also while live); when stale it is labelled stale and confidence drops one level |

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

```sh
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](mcp/) 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](mcp/README.md) for client configuration and payment safety.

## Use

Command line:

```sh
hodlodds status
hodlodds markets
hodlodds coverage <MINT> --chain solana --platform pumpfun
hodlodds risk <MINT> --keypair ~/.config/hodlodds/wallet.json --pay-to <RECIPIENT> --network solana
hodlodds risk <MINT> --keypair ~/.config/hodlodds/base-wallet.json --pay-to <BASE_RECIPIENT> --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 <MINT> --keypair ... --pay-to ... --network solana
```

Python:

```python
from hodlodds import HodlOdds, HodlOddsError

with HodlOdds("https://api.hodlodds.com", keypair="~/.config/hodlodds/wallet.json",
              network="solana", pay_to="<RECIPIENT>", max_price_usdc="0.01") as client:
    print(client.status()["state"])
    print(client.markets())
    print(client.coverage("<MINT>", chain="solana", platform="pumpfun"))
    try:
        answer = client.risk("<MINT>")
        row = answer.data["row"]
        print(row["p_crash_60m"], row["confidence"]["level"], 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.
```

`<RECIPIENT>` 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.

```python
base = HodlOdds("https://api.hodlodds.com", keypair="~/.config/hodlodds/base-wallet.json",
                network="base", pay_to="<BASE_RECIPIENT>", 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.

```python
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"]["level"])
# 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("<MINT>")
print(last_k