链上数据 API:巨鲸转账、交易所资金流与代币解锁
简而言之
- 链上数据 API 返回已解码的区块链事件:哪种代币、从谁转到谁、价值多少美元。原始数据来自节点,索引器把它整理成表,而地址标签始终只是可能出错的归属判断。
- 交易者关注交易所的充币和提币、大额转账、团队钱包动向、永续 DEX 持仓、解锁、领取、黑客攻击和大额 DEX 兑换。充入交易所并不一定意味着卖出。
- 在 Genesis API 中,九个链上分区从 Start 套餐起可用,而 DEX 兑换、分析和币种摘要需要 Pro 或 Max。各分区没有时间参数,所以时间窗口和资金流合计由你的代码计算。
链上数据 API 是一个 HTTP 接口,提供已经收集、换算成美元并加上标签的区块链事件:哪种代币、从哪个地址、转到哪个地址、通过哪笔交易。借助这样的 API,你无需自己运行节点或索引器,就能追踪巨鲸转账、交易所流入、代币解锁和 DEX 上的大额兑换。这里的巨鲸指持有大量某种币、其转账足以影响市场的地址。
链上数据从哪里来
数据经过三层:节点存储区块,索引器把区块转成事件行,标签库给地址命名。
节点:区块和日志
区块链节点存储区块,并通过 JSON-RPC 提供访问。在以太坊及兼容链上,ERC-20 代币转账会作为 Transfer(address indexed _from, address indexed _to, uint256 _value) 事件写入交易日志,标准还建议在铸造新代币时以 0x0 作为发送方发出同样的事件(EIP-20)。
eth_getLogs 方法返回符合过滤条件的日志:区块范围 fromBlock 和 toBlock、合约 address 以及事件 topics(Ethereum JSON-RPC)。日志包含地址、区块号、交易哈希和以代币最小单位表示的数量。区块里没有美元价格、没有所有者名称,也没有交易所标记。
索引器:从日志到表
索引器按顺序读取区块,解码事件,并分入各个表:转账、兑换、资金池变动。它把数量除以 10 的代币 decimals 次方(八位小数就是除以 100,000,000),再乘以区块时刻的价格,得到美元价值。
接着是阈值:数据流只保留超过设定金额的转账,同一地址的一连串小额转账会合并成一行。为多条链搭建这样的流水线本身就是一个项目,而链上数据 API 一次请求就返回它的产出。
地址标签:地址背后是谁
标签是附在地址上的名称:“Binance”“项目金库”“做市商”。它依据证据设定:该地址把币转给已知的交易所钱包、项目自己公布了地址、该地址从归属权(vesting)合约收到代币。这些都没有所有者确认,所以标签可能过时,也可能就是错的。
没有证据的地址保持匿名:在 Genesis API 文档的示例中,这样的发送方显示为缩短后的地址 0xec01…d1a5。
哪些链上事件对交易者重要
一个假设的例子:一个上午内,某项目价值 $2,000,000 的币流入交易所,同时有 $500,000 从团队钱包转到做市商的地址。单看每个事件说明不了多少;放在一起,就值得去查看价格、持仓量和解锁时间表。
| 事件 | 你看到什么 | 通常如何解读 |
|---|---|---|
| 充入交易所 | 币到达交易所地址 | 可能是卖出、抵押或调仓 |
| 从交易所提出 | 币转到外部地址 | 自行保管、DeFi 或另一家交易所 |
| 大额转账 | 地址之间超过阈值的转账 | 巨鲸在转移仓位 |
| 团队钱包 | 来自基金会、金库或创始人地址的动向 | 充入交易所比内部转移分量更重 |
| 永续 DEX 持仓 | 多头或空头:规模、价格、平台 | 巨鲸的押注和强平风险 |
| 解锁 | 释放的日期、比例和价值 | 该币的新增供应 |
| 领取 | 来自空投、归属或奖励的代币 | 领取者可能立即卖出 |
| 铸造和跨链桥 | 代币发行、跨链转移 | 稳定币铸造意味着资金流入 |
| 黑客攻击 | 协议、损失、攻击手法 | 对该代币及相关链的风险 |
| DEX 兑换 | 方向、金额、占池比例、价格变动 | 交易所反应之前的价格偏移 |
永续合约的去中心化交易所,即永续 DEX,其持仓是可见的,因为这些平台公开数据。在 Hyperliquid 上,info 接口 POST https://api.hyperliquid.xyz/info 配合 clearinghouseState 请求,无需密钥就能返回任意地址的未平仓持仓和保证金(Hyperliquid 文档)。CEX 不公开其他交易者的持仓,只提供持仓量这类汇总数据。
解锁是按归属计划释放团队、投资者或基金会的代币,这种计划会按固定时间表分批发放。日期事先已知,所以市场可能在事件发生前就把抛压计入价格。
DEX 兑换会在同一个区块内推动资金池价格。一个假设的例子:在流动性为 $1,200,000 的池子里买入 $150,000,占池子的 150,000 / 1,200,000 × 100 = 12.5%。池子价格明显变动,而在交易所上,这种变动会更晚才出现,或者根本不出现。DEX 与 CEX 的价格对比见 DEX API 一文。
黑客攻击在链上表现为从协议合约转出的资金。跨链桥比其他协议更常遭到攻击,因为它们的合约里存着大额资金:重要案例见区块链跨链桥一文,交易所被盗事件见 Bybit 黑客事件的分析。
延迟与确认
从一笔交易到你代码里的一行数据,要经过几秒到几分钟,这就是数据的延迟。对每日资金流概览几乎没有影响,但当你针对一笔大额充币或兑换做出反应时,它决定了结果。
网络确认
在以太坊上,新区块每个 slot 可以出现一次,即每 12 秒,并在大约 15 分钟后最终确认(ethereum.org)。除非损失巨额 ETH,否则已最终确认的区块无法更改。只需要已稳定数据的索引器,可以读取到 finalized 标签为止的区块,这是节点对最新最终确认区块的称呼。
交易所在交易达到最低网络确认数后才会为充币入账,以 Binance 为例,这个最低数对每种币各不相同(Binance 常见问题)。所以充入交易所的币在链上可见,早于所有者能够卖出这些币。
数据延迟
在 Genesis API 文档的兑换示例中,ts = 1794675511 是兑换时间,published_at = 1794675523 是发布时间:相差 1794675523 − 1794675511 = 12 秒。在此之上还要加上 meta.freshness_sec 中你的套餐的数据新鲜度(Start 为 30 秒,Pro 为 10 秒,Max 为 5 秒)和你的轮询间隔。
| 阶段 | 耗时 | 含义 |
|---|---|---|
| 以太坊区块 | 12 秒一个 slot | 交易可见但尚未最终确认 |
| 以太坊最终确认 | 约 15 分钟 | 区块不会再变 |
| 交易所入账 | 交易所的最低确认数 | 每种币不同 |
| 兑换发布 | 示例中为 12 秒 | 记录还不是 final |
final 状态 | 兑换后至少 5 分钟 | 30 秒和 5 分钟后的价格已知 |
| Genesis API 交付 | 30、10 或 5 秒 | Start、Pro 和 Max 套餐 |
对于兑换,带有未验证记录的 period=live 数据流更快,但如果这笔兑换其实只是流动性调仓,记录可能会消失。final=true 参数只保留已验证的兑换,它们至少晚 5 分钟到达。
Genesis API 中的链上数据
Genesis API 返回 Genesis OnChain 分区的数据流:转账行已经带有发送方和接收方标签、美元和代币数量、交易哈希以及浏览器链接。请求是 HTTP GET,密钥放在 X-API-Key 请求头中,响应是带 data 字段和 meta 块的 JSON。
| Endpoint | 返回内容 | 套餐 |
|---|---|---|
/onchain/{section} | 9 个链上分区之一 | Start、Pro、Max |
/onchain | 一个对象中的全部 9 个分区 | Start、Pro、Max |
/onchain/dex-swaps | 大额 DEX 兑换 | Pro、Max |
/onchain/analytics | 24h 或 7d 的合计 | Pro、Max |
/onchain/coin/{symbol} | 7 天币种摘要 | Pro、Max |
分区以数据流命名:large-transfers、cex-flows、mint-bridge、team-wallets、perp-positions、unlocks、claims、hacks 和 coin-traffic,其中 coin-traffic 保存同一种币流向同一目标的一连串转账。过滤参数是 min_usd 和 coin,解锁还有取值为 upcoming 或 past 的 when。没有时间参数,所以窗口要根据 ts 字段计算。
请求价值超过 $1,000,000 的即将解锁的代币:
curl -G "https://api.genesisarbitrage.com/v1/onchain/unlocks" \
-d when=upcoming -d min_usd=1000000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
解锁行包含 unlock_percent 和 unlock_value_usd(比例和价值)、hours_left(距事件的小时数)以及 allocations(按接收方的明细)。
Pro 和 Max 另外增加三个 endpoint。/onchain/dex-swaps 返回大额兑换,附带占池流动性比例、预估价格冲击以及 30 秒和 5 分钟后的价格变动(文档中的 DEX 概览)。/onchain/analytics 计算 24h 或 7d 的合计:kpi.cex_in、kpi.cex_out、kpi.cex_net 以及各交易所的资金流(OnChain 分析)。/onchain/coin/{symbol} 汇总一种币 7 天内的事件、兑换和解锁,并附上它的 CEX 价格、OI 和资金费率(OnChain 币种)。
只有 200 响应才占用额度,在 Trial 上链上 endpoint 会返回 403 plan_restricted。Start 每月 $50,含 2M 次调用;Pro $100,含 5M 次;Max $200,含 10M 次(Genesis API 价格)。每个参数和字段及响应示例都在链上 endpoint 指南中。
不写代码也能看到同样的数据流:Genesis OnChain 仪表盘、DEX 概览里的兑换,以及 OnChain 分析里的日度和周度合计。
Python:某种币在窗口内的交易所充币
一个假设的例子:6 小时内,五笔 ARB 转账到达交易所,分别为 $640,000、$520,000、$410,000、$330,000 和 $150,000。合计 640,000 + 520,000 + 410,000 + 330,000 + 150,000 = 2,050,000,所以越过了 $2,000,000 的阈值。第一笔转账超过 6 小时后会移出窗口:2,050,000 − 640,000 = 1,410,000,合计再次低于阈值。
cex-flows 没有 direction 字段,所以方向要从标签判断:to_name 中是交易所表示充币,from_name 中是交易所表示提币。响应是该分区的当前数据流,所以脚本按 tx_hash 保存充币记录,并自行丢弃旧记录。这样窗口合计就不会在多次轮询之间被重复计算。
import os
import time
import requests
API = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
COIN, MIN_USD = "ARB", 50_000
WINDOW = 6 * 3600 # 窗口,单位秒
ALERT_USD = 2_000_000 # 触发提醒的充币合计
CEX = ("binance", "okx", "bybit", "coinbase", "kraken")
deposits = {} # tx_hash -> (ts, usd)
alerted = False
def to_exchange(row):
label = (row.get("to_name") or "").lower()
return any(name in label for name in CEX)
while True:
r = requests.get(f"{API}/onchain/cex-flows", headers=HEADERS,
params={"coin": COIN, "min_usd": MIN_USD},
timeout=15)
if r.status_code in (429, 503): # 限流或重建
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
body = r.json()
for row in body["data"]:
if row.get("tx_hash") and to_exchange(row):
deposits[row["tx_hash"]] = (row.get("ts") or 0,
row.get("usd") or 0)
start = time.time() - WINDOW
deposits = {h: v for h, v in deposits.items() if v[0] >= start}
total = sum(usd for _, usd in deposits.values())
print(f"{COIN}:6 小时内流入交易所 ${total:,.0f},"
f"转账 {len(deposits)} 笔")
if total >= ALERT_USD and not alerted:
print("已越过阈值:请检查价格、OI 和资金费率")
alerted = total >= ALERT_USD
time.sleep(body["meta"]["freshness_sec"])
CEX 元组保存标签子串;请加入该币上市交易的交易所。脚本只做统计和打印:Genesis API 不会下单,交易决定由你自己做出。
带 coin 和 min_usd 的请求,其响应不带 ETag,所以每次轮询都会占用一次调用。在 Start 上间隔 30 秒,30 天内是 2,592,000 / 30 = 86,400 次调用,占 2M 额度的 4.32%。如果要看十几种币,就不带过滤地获取 /onchain/cex-flows 数据流,然后自己拆分:完整数据集带有 ETag,在数据没变时,带 If-None-Match 重复请求会返回 304,不占用额度。
低于 min_usd 的转账不会被统计:同一种币流向同一家交易所的一连串小额转账会归入 coin-traffic,字段包括 direction、total_usd、count 和 window_hours。
如何解读交易所充币
同样是 6 小时内到达交易所的 $2,050,000 ARB,可能是为卖出做准备,可能是期货的抵押品,也可能是所有者自己账户之间的转移。单独一行数据看不出是哪一种。
| 情形 | 还能看到什么 | 如何核对 |
|---|---|---|
| 准备卖出 | DEX 上出现卖单,价格走弱 | 带 side=sell 的 /onchain/dex-swaps |
| 期货抵押 | 持仓量增加,资金费率变化 | /market/open-interest、/funding/rates |
| 内部调仓 | 同一家交易所有对应的提币 | cex-flows 中的 from_name、浏览器 |
| 团队或基金卖出 | 发送方是团队钱包 | team-wallets、unlocks |
同一种币上的多个事件比单个事件分量更重:充入交易所、来自团队钱包的转账和即将到来的解锁。你可以在一个 /onchain/coin/{symbol} 响应中同时看到它们,事件旁边就是带有 oi_usd 和 funding_8h 的 cex 块。表中的 /market/open-interest 和 /funding/rates endpoint 从 Trial 起可用。
其他市场数据,以及如何为任务选择数据源,请见加密货币 API概览。
常见问题
链上数据中的地址标签有多准确?
标签依据证据设定,地址所有者并不确认,所以不可能完全准确。把某个地址与已知钱包联系起来的转账越多,结论越可靠,而新地址更常保持匿名。请通过浏览器链接核对每一个大额事件。
Genesis API 有链上历史数据吗?
没有深度归档。最长的窗口是 7 天:兑换和分析用 period=7d,以及 7 天币种摘要,而已过去的解锁来自 when=past。要获得长期历史,请在每次轮询时按 tx_hash 或 id 自行保存记录。
DEX 兑换的 pending 和 final 状态是什么意思?
这是 facts 字段,即记录的验证状态。pending 表示兑换已发布,兑换之后的价格仍在等待;publish 和 30s 是中间阶段;final 表示记录已验证,30 秒和 5 分钟后的价格已知;unavailable 表示未能收集到相关事实。在状态变为 final 之前,记录可能消失,所以请按 id 保存兑换,或请求 final=true。
我能免费用 API 追踪巨鲸吗?
你可以通过 JSON-RPC 从自己的节点或公共 endpoint 获取原始数据,但标签、美元金额和阈值就得自己来建。Genesis API 没有免费套餐:链上分区从每月 $50 的 Start 套餐开始,DEX 兑换和分析从 $100 的 Pro 开始。