Back to Details

hodlmm-signal-allocator

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

What it does

功能介绍

Reads three live data sources in sequence — the active HODLMM pool's 24h APR, approved signals from the aibtc.news bitcoin-macro beat, and the Bitcoin Developer Quantum Readiness Index — and computes a single risk-adjusted yield score. When that score exceeds the minimum threshold (≥60) and five safety gates pass, it executes a Bitflow swap (STX → sBTC) to align the wallet for optimal HODLMM deposit entry. Every execution is logged with signal IDs, readiness index snapshot, and the Hiro explorer link.
依次读取三个实时数据源——当前HODLMM资金池的24小时年化收益率（APR）、aibtc.news比特币宏观板块的核准信号，以及比特币开发者量子准备指数——并计算出单一的风险调整后收益评分。当该评分超过最低阈值（≥60）且通过五项安全校验时，将执行Bitflow兑换操作（STX → sBTC），使钱包达到存入HODLMM的最优状态。每次执行都会记录信号ID、准备指数快照以及Hiro浏览器链接。

Why agents need it

为什么Agent需要它

Entering a HODLMM position requires two things most agents handle separately: knowing when macro conditions favor a yield allocation, and having the right token ratio at the active bin. Agents acting on stale or low-quality signals over-allocate to HODLMM during unfavorable windows and under-allocate during yield spikes. This skill closes that gap by gating the swap on verified signal quality and quantum risk — if the intelligence layer is silent or uncertain, the skill does nothing and says why.
No other skill in this registry combines news signal intelligence with Quantum Readiness risk adjustment as a DeFi execution gate.
进入HODLMM头寸需要两件大多数Agent分开处理的事：了解宏观环境何时适合分配收益，以及在当前交易区间拥有正确的代币比例。依据过时或低质量信号操作的Agent，会在不利窗口过度分配HODLMM，而在收益峰值时分配不足。本技能通过将兑换操作与已验证的信号质量和量子风险绑定，填补了这一空白——如果智能层无信号或存在不确定性，技能将不执行任何操作并说明原因。
本技能是技能库中唯一将新闻信号智能与量子准备风险调整结合作为DeFi执行触发条件的技能。

Safety notes

安全说明

Five hard-coded gates execute in order before any swap:
  1. Signal quality gate — 
    signal_score < 60
    → 
    status: "blocked"
    . Derived from aibtc.news approved bitcoin-macro signals, 24h window, recency-weighted.
  2. Quantum risk gate — 
    (100 - readiness_index) / 100 × 0.2 > 0.15
    → 
    status: "blocked"
    . Quantum Power Map must show Readiness Index ≥ 25 before long-duration HODLMM allocation proceeds.
  3. Spend cap — 
    --amount-stx
    hard-coded max: 500 STX. Amounts above this return 
    status: "blocked"
    .
  4. STX reserve — wallet must retain ≥ 10 STX post-swap for gas. Refused if not satisfied.
  5. Price impact — Bitflow quote must show ≤ 1.5% price impact. Wider spreads return 
    status: "blocked"
    .
--confirm
is required for live execution. Without it, 
run
returns full simulation output with 
status: "blocked"
and reason 
CONFIRM_REQUIRED
. Cooldown: 6 hours between executions, enforced from 
~/.hodlmm-signal-allocator-state.json
.
在执行任何兑换操作前，会依次触发五项硬编码校验：
  1. 信号质量校验 — 
    signal_score < 60
    → 
    status: "blocked"
    。源自aibtc.news核准的比特币宏观信号，基于24小时窗口并按时效性加权。
  2. 量子风险校验 — 
    (100 - readiness_index) / 100 × 0.2 > 0.15
    → 
    status: "blocked"
    。在进行长期HODLMM分配前，量子力量图谱必须显示准备指数≥25。
  3. 支出上限 — 
    --amount-stx
    硬编码最大值：500 STX。超过该金额将返回
    status: "blocked"
    。
  4. STX储备 — 钱包在兑换后必须保留≥10 STX作为燃气费。若不满足则拒绝执行。
  5. 价格影响 — Bitflow报价必须显示≤1.5%的价格影响。价差过大将返回
    status: "blocked"
    。
实时执行需要
--confirm
参数。若未添加该参数，
run
命令将返回完整模拟输出，状态为
status: "blocked"
，原因是
CONFIRM_REQUIRED
。冷却机制：两次执行间隔需6小时，通过
~/.hodlmm-signal-allocator-state.json
强制执行。

Commands

命令

CommandDescription
doctor
Health check: Bitflow APIs, aibtc.news signals API, Quantum Power Map, BitflowSDK import
scan --pool <id> --wallet <addr>
Read HODLMM APR, fetch signal score, compute quantum risk factor, evaluate all gates
run --pool <id> --wallet <addr> --amount-stx <n> [--confirm] [--dry-run]
Execute Bitflow swap after all 5 gates pass. 
--dry-run
simulates without broadcasting.
Pool IDs (from 
bff.bitflowapis.finance/api/quotes/v1/pools
): 
dlmm_1
(STX-sBTC), 
dlmm_3
(STX-xBTC). Default: 
dlmm_1
.
命令描述
doctor
健康检查：Bitflow API、aibtc.news信号API、量子力量图谱、BitflowSDK导入情况
scan --pool <id> --wallet <addr>
读取HODLMM年化收益率、获取信号评分、计算量子风险系数、评估所有校验项
run --pool <id> --wallet <addr> --amount-stx <n> [--confirm] [--dry-run]
通过所有5项校验后执行Bitflow兑换。
--dry-run
参数将模拟操作而不广播交易。
资金池ID（来自
bff.bitflowapis.finance/api/quotes/v1/pools
）：
dlmm_1
（STX-sBTC）、
dlmm_3
（STX-xBTC）。默认值：
dlmm_1
。

Output contract

输出约定

All commands emit a single JSON object to stdout:
json
{
  "status": "success | error | blocked",
  "action": "Human-readable summary of outcome",
  "data": {},
  "error": { "code": "ERROR_CODE", "message": "...", "next": "How to resolve" }
}
doctor
data fields: 
{ checks: { bitflow_quotes, bitflow_app, aibtc_signals, quantum_map, bitflow_sdk }, degraded: string[] }
scan
data fields: 
{ pool_id, pool_apr_24h, adjusted_apr, signal_score, quantum_risk_factor, readiness_index, signals_used: [...], gates: { signal_ok, quantum_ok, cooldown_ok }, recommendation, wallet_stx_balance, wallet_sbtc_balance }
run
success data fields: 
{ txId, explorerUrl, amount_in_stx, amount_out_sbtc_estimated, price_impact_pct, signal_score, readiness_index, signal_basis: [...], quantum_risk_factor, adjusted_apr, next_eligible_at }
所有命令都会向标准输出（stdout）输出单个JSON对象：
json
{
  "status": "success | error | blocked",
  "action": "操作结果的可读摘要",
  "data": {},
  "error": { "code": "ERROR_CODE", "message": "...", "next": "解决方法" }
}
doctor
数据字段： 
{ checks: { bitflow_quotes, bitflow_app, aibtc_signals, quantum_map, bitflow_sdk }, degraded: string[] }
scan
数据字段： 
{ pool_id, pool_apr_24h, adjusted_apr, signal_score, quantum_risk_factor, readiness_index, signals_used: [...], gates: { signal_ok, quantum_ok, cooldown_ok }, recommendation, wallet_stx_balance, wallet_sbtc_balance }
run
成功数据字段： 
{ txId, explorerUrl, amount_in_stx, amount_out_sbtc_estimated, price_impact_pct, signal_score, readiness_index, signal_basis: [...], quantum_risk_factor, adjusted_apr, next_eligible_at }

Known constraints

已知限制

  • Requires 
    @bitflowlabs/core-sdk
    installed (
    bun install
    in skill directory)
  • Live execution requires wallet funded with ≥ (amount + 10 STX gas reserve)
  • HODLMM API (
    bff.bitflowapis.finance
    ) has a 500 req/min public rate limit
  • Quantum Power Map data.json updates when developer scores change; stale data (>7 days) triggers a 
    doctor
    warning but does not block 
    scan
  • Signal score of 0 (no approved signals in 24h window) always blocks execution
  • 需要安装
    @bitflowlabs/core-sdk
    （在技能目录中执行
    bun install
    ）
  • 实时执行要求钱包余额≥（兑换金额 + 10 STX燃气储备）
  • HODLMM API（
    bff.bitflowapis.finance
    ）的公共请求限制为500次/分钟
  • 量子力量图谱data.json会在开发者评分变更时更新；过期数据（>7天）会触发
    doctor
    警告，但不会阻止
    scan
    命令执行
  • 信号评分为0（24小时窗口内无核准信号）时将始终阻止执行

Origin

来源

Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @IamHarrie-Labs Competition PR: https://github.com/BitflowFinance/bff-skills/pull/203
AIBTC x Bitflow Skills Pay the Bills竞赛获胜作品。 原作者：@IamHarrie-Labs 竞赛PR：https://github.com/BitflowFinance/bff-skills/pull/203