hodlodds-mcp

hodlodds — Python 客户端

按回答付费的 Solana memecoin 暴跌概率，使用 x402 按请求付费（Solana 或 Base 上的 USDC）。无需账户或 API 密钥。

https://api.hodlodds.com 上的 API 接受付款。付费前，请查看其免费状态、市场和覆盖范围端点。本地测试服务可使用 Solana devnet 或 Base Sepolia。

它能回答什么

该代币的价格在接下来的 60 分钟内下跌 90% 或以上的概率是多少？

0.04 表示在预测时间窗口内发生所定义事件的估计概率为 4%。置信度描述的是该概率区间的历史校准情况，而非对该代币的保证。数值越高，风险越大；但数值较低并不代表安全：较小幅度或较缓慢的下跌不计入其中，而且概率每分钟都会变化。

暴跌是指在接下来的 60 分钟内，SOL 计价的已完成一分钟收盘价至少比参考价格低 90%。覆盖范围：以 SOL 报价的 pump.fun 毕业代币。每个回答都会根据该概率区间内过去预测与实际情况的吻合程度，附带一个置信度等级（high / medium / low）。

dd_60 是最新收盘价除以前 60 分钟内的最高收盘价，再减去一。零表示代币处于该小时的最高点；dd_60 <= -0.90 表示其在该小时内已经下跌至少 90%。数据行会显示 already_crashed（true、false；若回撤幅度未知则为 null）；更早之前发生的暴跌会显示为 false。crashed_within_24h 和 last_crash_as_of 表示 API 快照是否在过去 24 小时内观察到该代币的 dd_60 <= -0.90，以及最近一次此类快照的时间（UTC Unix 时间戳，单位为秒）。记忆只知道 API 收到的快照：如果暴跌完全发生在 API 中断期间，就不会被记录。当记忆无法确认完整的 24 小时时，这两个字段都会是 null：例如，某次快照到达时距离记忆中记录的上一次快照已超过一小时后 23 小时内（可能是数据源中断，或记忆文件被替换或还原）；记忆超过大小限制后（直到被丢弃代币的记录过期）；以及存储出现故障期间。新部署启动时记忆可用。任一暴跌标记都会在 summary 中添加 note 和暴跌背景信息：暴跌后较低的暴跌概率并不代表已恢复或安全。 在约 2% 以下的区间，观察到的暴跌率最高曾达到预测值的约两倍，但绝对差值不到一个百分点。概率为 0.5% 至 2% 的回答带有 confidence: low；低于 0.5% 的回答置信度最高为 medium，并带有 direction: historically under-predicted。

路由	价格	备注
GET /v1/status	免费	数据源状态（live / stale / down）、时效、事件、正常运行时间
GET /v1/meta	免费	定义、价格、付款详情、模型卡
GET /v1/markets	免费	可用的数据链、平台和覆盖范围
GET /v1/coverage/{mint}	免费	单个代币的覆盖阶段和原因
GET /v1/risk/{mint}	$0.01	单个代币的最新概率
GET /v1/board?limit=N	每个返回的代币 $0.005	请求 10–500 个代币，或包含 1–100 个不同 mint 的关注列表；仅按实际返回的代币付费，返回为空则免费
GET /v1/risk/{mint}/last	$0.002	最近一次已知概率，最多为 30 分钟前的数据（实时运行时也可使用）；数据过期时会标注为过期，且置信度降低一级

常规风险和行情板路由仅对最新且在覆盖范围内的回答收费。可选择使用 /last 路由获取明确标注的最近一次已知概率，收费数据不得超过其 30 分钟时限。未覆盖和不符合条件的回答免费。若拒绝响应带有 HodlOdds-Charged: no，则视为免费，除非成功付款回执与之矛盾；这也包括超大标头导致的 431。如果签名后资格状态发生变化，该免费拒绝不会产生待处理付款。

数据新鲜度

评分每 60 秒重新计算一次，在每分钟结束后约 20 秒，基于截至 as_of 的已完成一分钟 K 线。每个评分涵盖其 as_of 时间之后的 60 分钟，仅在下次更新前有效；同一代币的赔率可能在相邻两分钟间大幅上涨。评分约在每分钟 :20 开始计算；计算和发布可能导致数据延迟。作出决策时，请在采取行动前立即刷新；持续监控时，请每分钟刷新一次，并检查 as_of 是否已更新到新的一分钟。API 的新鲜度截止时间是独立设置的：默认情况下，在 issued_at 之后超过 120 秒，或超过 expires_at 后，数据会变为 stale。新请求不会重启预测窗口。

可选启用的 /v1/risk/{mint}/last 路由会返回签发后最多 30 分钟内存储的赔率，包括恰好 1800 秒时的赔率。该路由在数据仍为实时状态时也可用。数据过期时，置信度会从高降为中，或从中降为低；低置信度保持低，缺失的置信度仍保持缺失。原始预测时长和到期时间保持不变。

安装

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

Python 3.10+。依赖项：httpx、certifi>=2026.10.19 和官方的 x402[svm,evm]==2.25.0 SDK（固定版本）。

MCP 服务

独立的 hodlodds-mcp package 提供本地 stdio 工具，用于市场发现和崩盘赔率， 并设有每次调用和会话级支付限额。

pip install hodlodds-mcp 请参阅 MCP README，了解客户端配置和支付安全。

使用

命令行：

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：

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> 是你所选支付网络的收款地址，发布在 GET /v1/meta 中。请在代码中验证并固定该地址：如果报价将款项支付给其他人，客户端会拒绝。

网络：devnet 和 solana（主网；mainnet 是别名）使用 Solana JSON 密钥文件；base-sepolia 和 base 使用 EVM 密钥文件（{"private_key": "0x..."}，权限模式为 0600）。两条链上的价格相同，API 都会提供这两种支付方式；客户端只会在你选择的网络上签名。

base = HodlOdds("https://api.hodlodds.com", keypair="~/.config/hodlodds/base-wallet.json",
                network="base", pay_to="<BASE_RECIPIENT>", max_price_usdc="0.01")

看板选项：limit 为 10–500（默认值为 50）；sort 可选 lowest_risk（默认值）、riskiest、liquidity、newest、active；筛选条件包括 max_risk、min_risk、min_liquidity_sol、min_age_min、max_age_min、min_trades_5、min_confidence（high/medium/low）和 include_crashed（True/False）。 总价为 0.005 × 返回的代币数；在 Python 中传入 max_price_usdc，或在命令行中传入 --max-price，且数值至少要达到总价。每次调用的默认上限为 0.01 USDC，因此看板通常需要显式设置更高的上限。硬性上限仅看板调用为 2.5 USDC，单个风险/最新值调用为 1 USDC。超过你的上限时，客户端会在签名前抛出 PriceLimitError（属于 HodlOddsError）；其中的 price_atomic 和 limit_atomic 分别表示报价总额和你的上限，单位为 USDC 最小单位（1 USDC = 1,000,000）。 min_trades_5 接受 0 到 9223372036854775807 之间的整数。

兼容性：0.2.0 版的 safest 排序仍可作为 lowest_risk 的别名使用，支付网络别名 mainnet 仍表示 solana。这些旧写法已从示例中弃用；现有调用仍可正常使用。

对于 lowest_risk 及其别名 safest，如果未指定这些筛选条件，服务端会应用 min_trades_5=3、min_liquidity_sol=5 和 include_crashed=false，以免交易稀少、流动性不足或近期崩盘的代币占据列表。崩盘筛选会同时排除 already_crashed 和 crashed_within_24h 行。显式设置的值会覆盖默认值，包括 min_trades_5=0、min_liquidity_sol=0 和 include_crashed=True（命令行：--min-trades 0 --min-liquidity 0 --include-crashed）。 其他排序方式保留原有的选择逻辑。显式指定的 mints= 观察列表不会应用这些默认值：崩盘持仓仍会显示并标记，除非你显式指定 include_crashed=False。

赔率最低的通常是交易最少的代币；默认筛选条件会排除大多数不活跃或近期崩盘的代币，但并非全部。

看板响应会返回生效的 filters、defaults_applied（未添加任何默认值时为空）以及 excluded_by_defaults，即仅因这些默认值而在数量限制生效前移除的行数。402 报价正文也会显示 defaults_applied 和 excluded_by_defaults；它们不属于已签名报价。如果 API 无法获取近期崩盘记录，默认值说明会指出这一点，崩盘筛选也只会使用 already_crashed。报价会精确绑定客户端自身规范化后的参数。服务端在选择和定价行时，会确定性地应用其文档中说明的默认值；客户端不会将这些默认值添加到已签名查询中。

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_known.data["age_s"], last_known.data["freshness"])

last() 的费用为 0.002 USDC，可返回最长 30 分钟前的最近已知赔率，包括数据流正常运行期间。请检查 stale、age_s、freshness 和 horizon_remaining_s；购买响应不会续期其预测。

看板报价变更时

看板返回 409 且 code: "offer_changed"，表示从报价到付费请求之间，匹配结果集发生了变化；服务器会在该拒绝响应中标记 HodlOdds-Charged: no。在当前 API 中，此 409 仅会返回给已签名请求，而已签名请求绝不会自动重试。 如果 HodlOdds-Charged: no 且没有冲突的收据，就表示未扣费，但客户端必须再次调用；SDK 不会自行重新签名。实际使用时， board() 会抛出 HodlOddsError，且 error.payment["charged"] == False；再次调用 board() 以获取新报价。若服务器行为异常， 再次自动授权可能会导致重复结算。监控循环会将已确认的免费拒绝视为跳过，并在下一个预定周期继续。付款状态不确定时，监控会停止，并需要进行对账。

仅作为一项安全措施，SDK 0.3.1 及更高版本会在签名前发生 409 且没有成功或状态不确定的收据时，仅请求一次新报价。 刷新时会使用相同查询，重新进行所有价格和预算检查，并且不会签名或扣款。

观察列表和市场筛选条件

传入 mints=[mint_a, mint_b]，将看板限制为 1–100 个不重复的 Solana 铸币地址。重复项会在发出任何请求前由本地拒绝（在服务器端也会免费返回 400）。观察列表的默认限制为其长度；显式指定的观察列表限制为 1–100。排序和筛选条件仍会生效。报价会在签名前绑定到经过规范化的精确选择结果，包括观察列表摘要。 只会对返回的行收费。answer.data["not_delivered"] 会报告未返回的请求铸币地址的覆盖情况和筛选事实；它不是评分。

hodlodds board --mints <MINT_A>,<MINT_B> --max-price 0.01 \
  --keypair ... --pay-to ... --network solana
hodlodds board --mints-file watchlist.txt --max-price 0.50 \
  --keypair ... --pay-to ... --network solana

在 --mints-file 中每行填写一个铸币地址；空行和 # 注释会被忽略。 两个观察列表标志不能同时使用，也可与 watch --board 搭配使用。

answer = client.board(mints=[mint_a, mint_b], max_price_usdc="0.01",
                      chain="solana", platform="pumpfun")
print(answer.data["rows"], answer.data.get("not_delivered", []))

chain 和 platform 用于选择数据市场，与付款所用网络相互独立。它们适用于 risk、last、coverage、board、watch 和 watch_board；CLI 对应选项为 --chain 和 --platform。Python 接受字符串、逗号分隔的字符串或列表。值不区分大小写；可使用链别名或 CAIP-2 ID。pump 和 pump.fun 是 pumpfun 的别名。列表包含 1–10 个不重复的受支持值，列表内条件为 OR 关系，两个筛选条件之间为 AND 关系。不受支持或相互矛盾的值会在付款前被拒绝。省略筛选条件会保留现有的默认选择。

使用 client.markets() / hodlodds markets 查看受支持的值；使用 client.coverage(mint) / hodlodds coverage <MINT> 了解某个代币是否受支持。 在 Base 上付款不会选择 Base 代币数据。实验性的非 SOL 排名仍不包含在付费看板中，可能会出现在免费的风险路由拒绝响应中。

监控代币

监控循环完全在客户端运行。选择 1 到 60 分钟的整数间隔； 必须指定 --max-spend，用于限制整个监控过程的 USDC 总支出。--max-price 仍会限制每次报价。示例（主网；请固定使用已公布的收款地址）：

hodlodds watch <MINT> --every 1 --max-spend 1.00 \
  --keypair ~/.config/hodlodds/wallet.json --pay-to <RECIPIENT> --network solana
hodlodds watch <MINT> --every 5 --max-spend 1.00 --max-calls 20 --alert-above 0.20 \
  --keypair ~/.config/hodlodds/wallet.json --pay-to <RECIPIENT> --network solana
hodlodds watch --board --limit 100 --sort riskiest --max-price 0.50 --every 5 --max-spend 2.00 --alert-above 0.20 --json \
  --keypair ~/.config/hodlodds/wallet.json --pay-to <RECIPIENT> --network solana

主网仍要求显式指定 --network solana 或 --network base，以及 --pay-to <recipient>。搭配 --board 时支持所有现有看板筛选条件。 每次调用的默认最高价格仍为 0.01；如需更大的看板，请显式调高。

连续运行的预估费用（未计入跳过的调用或总支出上限）：

目标	间隔	价格/次调用（USDC）	调用次数/小时	USDC/小时	USDC/24 小时
代币	1 分钟	0.01	60	0.60	14.40
代币	5 分钟	0.01	12	0.12	2.88
看板，限制为 100	1 分钟	至多 0.50	60	至多 30.00	至多 720.00
看板，限制为 100	5 分钟	至多 0.50	12	至多 6.00	至多 144.00
代币估算使用公布的 0.01 价格。看板估算按每枚代币 0.005 计算完整请求上限，即使匹配的代币较少或 --max-price 更低也是如此。实际支出使用每个已检查报价中的精确 USDC 原子单位金额。循环会在签署会超出剩余上限的报价前停止。上限必须为正数，且最多包含六位小数；调用 SDK 前请传入十进制字符串，以避免浮点运算。默认没有支出上限。

周期在 UTC 分钟边界的 :25 加 0–5 秒随机抖动时开始；五分钟监控则使用 :00、:05、:10 等时间点。首次调用会等待下一个计划边界。请求或消费者处理速度较慢时，会跳过错过的时段，而不是追赶。每个周期都会先检查免费的 /v1/status：

• 如果数据源的 state 不是 live，则返回跳过结果，不会付款。--stop-on-stale 会在此结果后结束；否则监控会继续。
• 如果 as_of 与上次已付费答案的分钟相同（或更早），循环会等待十秒，然后再次检查状态。如果仍未变化，则跳过，不会付款。由于发布时间可能在付款处理期间推进，因此比较的是已付费答案的 as_of。
• 出现新的实时分钟时，会通过现有付款检查调用一次付费路由。服务端也会在提供付费答案前再次检查数据新鲜度。监控不会使用过时的 /last 路由。

分数仅在下一分钟更新前有效。 每五分钟监控可以节省费用，但当前分数之间会有空档。数据源中断和分钟重复都不会产生费用。空看板也免费。--max-calls 统计付费路由调用次数，包括免费的空看板；跳过的状态检查不计入，监控在服务中断期间可以持续等待。

文本输出会显示 UTC 时间、as_of、精确到小数点后一位的赔率百分比（低于 0.1% 时显示 <0.1%，绝不显示 0.0%）、置信度以及总支出/上限。赔率达到或超过阈值（0 到 1）时会标记为 ALERT。看板会打印摘要以及每一行达到阈值的内容。--json 每个周期输出一个 JSON 对象：包含所有答案字段，以及含有 cycle、spent_usdc、cap_usdc、skipped_reason、utc 和 alert 的 watch。跳过的周期会包含状态字段，而非付费答案。金额使用精确的十进制字符串；对于答案，skipped_reason 为 null。估算信息和停止/错误消息会输出到 stderr，以确保 stdout 保持为有效的 JSON Lines。

# Use the configured client from the Python example above.
watch = client.watch(mint, every_minutes=5, max_spend_usdc="1.00",
                     max_calls=20, alert_above=0.20, stop_on_stale=False)
print(watch.estimate)  # available immediately, before any request
try:
    for answer in watch:
        print(answer.data, answer.watch, answer.payment)
finally:
    watch.close()

board_watch = client.watch_board(every_minutes=5, max_spend_usdc="2.00",
                                 limit=100, max_price_usdc="0.50", max_calls=4)
board_watch.close()

两种方法都会返回由生成器支持的可关闭迭代器，并产出 Answer 对象。answer.alerts 保存符合条件的行；watch.spent_atomic 提供整数形式的支出，watch.stop_reason 说明正常的限制停止或中断停止原因。客户端由调用方拥有并负责关闭。在周期之间关闭迭代器或按 Ctrl-C，都可以干净地停止。在已授权请求期间发生中断时，会报告结果不明确，并附上对账详情。

签署后，如果收到标记为 HodlOdds-Charged: no 的拒绝响应且没有成功付款回执，则会释放预留支出并返回跳过结果；监控会继续运行。这会计入 --max-calls。付款状态不明确、成功回执冲突或其他付款错误都会导致监控停止；不会重试付款，也不会自动赎回。未解决的尝试仍计入 spent_atomic。Python 会收到 HodlOddsError.payment；CLI 会保存一个私有待处理付款文件，供用户按下文所述显式赎回。其他请求错误和被拒绝的报价也会导致循环停止。在不明确的付款完成对账前，不要启动其他监控。

如果付款后答案丢失

付费请求最多等待 90 秒（paid_timeout，30–600）。如果授权后连接中断，请保留待处理记录，并使用明确的恢复流程，而不是再次付款：

• 服务器记录为未交付的已结算付款，可在 24 小时内兑换一次；兑换时仍会检查路由和答案是否符合条件。如果答案准备就绪时连接已经关闭，或者结算后来才得到确认，服务器会将答案记录为未交付。服务器已完成并发送的答案会记录为已交付，即使答案在传输途中丢失，兑换也会被拒绝并返回 409。
• 在 Python 中，错误对象会携带付款信息：client.redeem(error.payment) 会使用同一授权重新发送，并附带 HodlOdds-Redeem: 1。它不会签署新的付款，也不会再次结算。
• CLI 会将其保存到 ~/.config/hodlodds/pending/<id>.json（权限模式为 0600），并打印文件路径；大约两分钟后运行 hodlodds redeem <file>。
• 409 可能表示确认仍在等待中、未找到可兑换的付款、答案已交付，或者付款已兑换或过期。如果响应中提供了 Retry-After，请遵循其指示；兑换被拒绝时，请保留待处理记录。被拒绝的兑换不会签署或结算任何新付款；这本身并不能证明原付款失败。

CLI 的环境变量：HODLODDS_BASE_URL、HODLODDS_NETWORK、HODLODDS_KEYPAIR、HODLODDS_PAY_TO、HODLODDS_MAX_PRICE。 退出状态：0 表示成功，1 表示拒绝/API/传输失败，2 表示用法无效。

客户端内置的安全规则

• 只有在 402 报价通过所有检查后才会签署付款：x402 v2、所选网络、精确的 USDC、授权流程、固定的 payTo、在 Solana 上有效且不同于你的 facilitator 费用付款方、有界超时，以及价格不高于你的限额（默认 0.01 USDC；risk/last 的硬上限为 1 USDC，board 的硬上限为 2.5 USDC；使用精确的原子单位计算）。
• 绝不会自动重试付款。如果授权已发送后发生任何问题，错误信息会说明这一点，并附带详情（HodlOddsError.payment），以便你对照钱包历史记录核对，或兑换一次答案（见上文）。
• 密钥文件必须是常规的非符号链接文件，权限模式为 0600。文件仅在本地读取，不会打印或发送；只有由 SDK 签名的 USDC 转账授权会离开你的设备。请使用余额较低的专用钱包。
• 仅允许 HTTPS（本地测试服务除外，可使用普通 HTTP）。不跟随重定向，不使用环境代理，并限制请求头和请求正文的大小。
• 主网必须显式指定 network="solana"（或 "base"），并固定 pay_to；CLI 要求在命令行中指定 --network solana|base --pay-to ...。

安全性

该软件包要求使用 certifi>=2026.10.19，这是 httpx 使用的 TLS 根证书包。该版本在 CA 于 2026-10-20 公布事件后移除了“emSign ECC Root CA - G3”根证书；请运行 pip install -U hodlodds certifi 升级旧环境。

测试钱包（devnet / Base Sepolia）

hodlodds-wallet new ~/.config/hodlodds/my-devnet.json   # prints the public address only
hodlodds-wallet new --network base-sepolia ~/.config/hodlodds/base-sepolia.json

请通过 https://faucet.circle.com 为其注入测试 USDC（网络：Solana Devnet 或 Base Sepolia）。 切勿将真实资金存入测试钱包。

测试

python -m unittest discover -s tests -v

测试使用伪服务和伪 SDK 接口离线运行；安装指定版本的 SDK 后，其他测试还会在模拟所有 RPC 调用的情况下生成真实签名。

免责声明

赔率并非保证。本文不构成财务建议。低赔率并不意味着代币安全；崩盘可能毫无预警地发生。运营方也运行独立的交易系统，该系统可能会交易 HodlOdds 评分的代币；它绝不会收到客户请求或购买信息，也没有人可以付费更改评分。

许可证

MIT