Mirise1/soltrail

# soltrail 利用 Bitquery 索引的 Solana 数据，查找接近目标 USD 价值的历史原生 SOL 转账。 你只需提供日期、美元金额和粗略的当地时间。它会根据当天的价格将美元目标转换为 SOL 范围，并返回匹配的原生转账，按其与目标的接近程度进行排名。它通过在狭窄的时间窗口内查询 Bitquery 的索引，而不是通过 RPC 爬取链上数据，因此一次查找仅需少数几次 API 调用。 ## 工作原理 1. 使用历史 SOL/USD 价格（自动获取，或通过 `--sol-price-usd` 指定）将 USD 目标转换为 SOL 金额。 2. 围绕该金额构建一个 `±tolerance%`（容差百分比）的范围。 3. 依次尝试 `--timezone-offsets` 中的每个时区偏移量，并在返回准确匹配的第一个时间窗口时停止。 4. 每个时间窗口运行一次 Bitquery `transfers` 查询，由服务端根据时间和金额进行过滤。 5. 去重，仅保留普通的系统转账（见下文），根据与目标的偏差程度评分，并写入 JSON。 ## 环境要求 - Python 3.10+ - 一个 Bitquery 访问令牌 获取令牌： ## 安装说明 ``` cp .env.example .env # PowerShell: Copy-Item .env.example .env ``` 在 `.env` 中设置 `BITQUERY_TOKEN`；其他所有配置均有默认值。你也可以选择安装以获取 `soltrail` 命令： ``` pip install -e . # then: soltrail --help ``` 或者直接运行脚本，无需安装： ``` python scan_solana_bitquery.py --help ``` ## 使用方法 ``` # 使用来自 .env 的默认值 python scan_solana_bitquery.py # 在 command line 上覆盖 python scan_solana_bitquery.py --date 2026-04-15 --target-usd 200 --max-results 10 # 特定的本地窗口和 timezone python scan_solana_bitquery.py --date 2026-04-15 --target-usd 200 \ --local-window-start 11:45:26 --local-window-end 11:47:59 --timezone-offsets 3 # 不确定关于 timezone？依次尝试几个 python scan_solana_bitquery.py --date 2026-04-15 --target-usd 200 \ --local-window-start 11:46:07 --local-window-end 11:48:33 --timezone-offsets 0,3,5 ``` 添加 `-v` 以开启调试日志，或添加 `-q` 以仅显示警告。诊断信息会输出到 stderr；结果保存在 JSON 文件中。 ## 选项 | 选项 | 描述 | | --- | --- | | `--date` | 格式为 `YYYY-MM-DD` 的 UTC 日期。 | | `--target-usd` | 以 USD 为单位的目标转账价值。 | | `--tolerance-pct` | 允许偏离目标价值的百分比。 | | `--max-results` | 最多保存的匹配数量。 | | `--query-limit` | 每个时间窗口请求的最大 Bitquery 转账行数。 | | `--local-window-start` | 格式为 `HH:MM` 或 `HH:MM:SS` 的本地开始时间。 | | `--local-window-end` | 格式为 `HH:MM` 或 `HH:MM:SS` 的本地结束时间。 | | `--timezone-offsets` | 逗号分隔的待尝试 UTC 偏移量，例如 `0,3,5`。 | | `--sol-price-usd` | 手动覆盖 SOL/USD 价格。 | | `--include-non-pure-transfers` | 禁用严格的原生纯转账过滤器。 | | `-v` / `-q` | 详细 / 安静日志模式。 | 运行 `python scan_solana_bitquery.py --help` 查看完整列表。大多数选项也可以通过 `.env` 中的 `SOLTRAIL_*` 键读取；但命令行参数具有更高优先级。 ## 转账过滤器 默认情况下，扫描器仅保留简单的原生 SOL 系统转账，并丢弃任何看起来像 swap/AMM 管道操作的转账。它是根据同一次 `transfers` 查询已返回的字段来做出判断的——无需进行二次查询——仅当满足以下条件时才保留转账： - 该指令是 System Program 的 `transfer`， - 发送方同时也是签名者和手续费支付者， - 没有内部指令（inner instructions）， - 账户数量和顶层指令数量均较少。 这会过滤掉大多数 Pump.fun、Raydium、Jupiter 及类似平台的转账。这是一种启发式方法，因此对于任何重要信息请务必亲自人工核对。使用 `--include-non-pure-transfers` 可查看原始候选项。 ## 输出结果 结果将输出到 `matches__bitquery.json`。每条记录都包含签名、区块时间（UTC 时间和匹配到的时区时间）、SOL 金额、预估的 USD 价值、发送方/接收方、过滤器所使用的交易结构相关字段，以及接近度排名。 ``` { "date": "2026-04-15", "sol_price_usd": 152.31, "target_usd": 200.0, "results": [ { "signature": "5xEXAMPLE...signature", "block_time": "2026-04-15T08:46:12Z", "block_time_in_matched_timezone": "2026-04-15T11:46:12+03:00", "amount_sol": 1.313110105, "amount_usd_estimated": 200.01, "usd_distance_abs": 0.01, "source": "SenderPubkey...", "destination": "ReceiverPubkey...", "closeness_rank": 1, "is_closest_match": true } ] } ``` ## 成本说明 每个时区窗口对应一次 `transfers` 查询，并按顺序尝试直到有匹配结果为止——运气好的话，第一次猜测仅需一次调用。仅当默认时间窗口未能返回足够的高质量候选数据时才扩大 `--query-limit`；如果你已经知道具体时区，请精简 `--timezone-offsets`。 ## 注意事项 Solana 交易数据是公开的，此工具仅读取这些数据——请在 Bitquery 的服务条款范围内，将其用于你自己的查询和研究。

标签：Python, Solana, 代码示例, 区块链, 数据分析, 无后门, 逆向工具, 链上数据