Genesis API 链上数据:转账、资金流、解锁、DEX 兑换
简而言之
- /onchain/{section} 端点返回九个 Genesis OnChain 数据流中的任意一个,从大额转账到黑客事件,Start、Pro 和 Max 套餐均可使用。不带 section 的 /onchain 请求会在一个对象中返回全部数据流。
- 大额 DEX 兑换、24 小时或 7 天分析以及币种 7 天摘要仅限 Pro 和 Max 套餐。
- 地址标签只是归属判断,并非保证。转入交易所不一定意味着卖出,兑换记录也可能在验证后消失。
Genesis API 的链上端点返回 Genesis OnChain 板块的数据:大额代币转账、交易所充币与提币、团队钱包动向、永续 DEX 仓位、代币解锁、领取和黑客事件,以及 DEX 上的大额兑换。每一行都已带有发送方和接收方标签、USD 金额和区块浏览器链接。无需自建区块链索引器,就足以在自己的代码中追踪巨鲸并监控交易所资金流。
端点与套餐
| 端点 | 返回内容 | API 套餐 |
|---|---|---|
/onchain/{section} | 九个 Genesis OnChain 板块之一 | Start、Pro、Max |
/onchain | 九个板块合并在一个对象中 | Start、Pro、Max |
/onchain/dex-swaps | 大额 DEX 兑换 | Pro、Max |
/onchain/analytics | 24 小时或 7 天的 OnChain 分析 | Pro、Max |
/onchain/coin/{symbol} | 单个币种的 7 天摘要 | Pro、Max |
在 Trial 套餐上,所有链上端点都返回 403 plan_restricted。数据新鲜度在 Start 上为 30 秒,Pro 上为 10 秒,Max 上为 5 秒,相同的值也会通过 meta.freshness_sec 返回。密钥和第一个请求见快速开始,配额见 Genesis API 限额。
/onchain/{section} 的九个板块
section | 内容 | 仪表盘模块 |
|---|---|---|
large-transfers | 大额代币转账 | Large Transfers |
cex-flows | 交易所充币和提币 | CEX Deposits / Withdrawals |
mint-bridge | 代币铸造和跨链桥转账 | Mint / Bridge |
team-wallets | 团队钱包动向 | Team Transfers |
perp-positions | 永续 DEX 的大额仓位 | Perp. DEX Positions |
unlocks | 代币解锁 | Unlocks |
claims | 领取 | Claims |
coin-traffic | 某个币种流向同一目标的一系列转账 | Coin Traffic |
hacks | 黑客攻击与漏洞利用 | Hacks / Exploits |
每个模块展示什么、应关注哪些信号,见 Genesis OnChain 仪表盘指南,参数见文档。不带 section 的 /onchain 请求会在 data 中返回一个对象:键是板块名称,值是该板块的数据行。此时筛选条件对每个板块都生效。
| 参数 | 类型 | 作用 |
|---|---|---|
min_usd | number | 事件最小金额,USD |
coin | string | 单个币种的数据行;hacks 没有币种,因此返回空列表 |
when | string | 仅用于 unlocks:upcoming 或 past |
section | string | /onchain?section=… 请求使用的板块 |
when 取其他任何值都会返回 400 bad_request。下面是 coin-traffic 板块,即 data 数组中的一项:
curl "https://api.genesisarbitrage.com/v1/onchain/coin-traffic" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"ts": 1783802410,
"token": "LAB",
"direction": "deposit",
"target": "Gate-io",
"target_address": "0x8782163068c7cd74D2510768a61135C1e4Eb07b3",
"total_usd": 573796.98,
"count": 18,
"window_hours": 5.69,
"avg_usd": 31878,
"largest_usd": 59891.78,
"transfers": [
{
"ts": 1783788640,
"usd": 59891.78,
"from_name": "0xec01…d1a5",
"tx_hash": "0xbf44850a7dc16086c08cfb…",
"chain": "bsc",
…
}
]
}
板块字段
large-transfers、cex-flows、mint-bridge、team-wallets 和 claims 板块由转账组成;其他板块有各自的字段。
| 字段 | 所在板块 | 含义 |
|---|---|---|
ts、links | 所有板块 | 以 unix 秒表示的事件时间,以及现成的链接:文本 + url |
token / token_name | 转账、coin-traffic | 代币代码和全名 |
chain / chain_name、usd / amount | 转账 | 网络,以及 USD 和代币数量表示的金额 |
from_* / to_* | 转账 | 发送方和接收方:标签、地址、区块浏览器链接 |
tx_hash / explorer_url / arkham_url | 转账 | 交易哈希、区块浏览器和 Arkham 链接 |
direction、target / target_address | coin-traffic | 方向(deposit、withdrawal 或 transfer)和资金流目标 |
total_usd / count / window_hours、transfers[] | coin-traffic | 系列总额、转账笔数、以小时计的时间窗口和最大的几笔转账 |
side / size / price / platform | perp-positions | Long 或 Short、规模、价格、平台 |
unlock_percent / unlock_value_usd / hours_left / allocations | unlocks | 解锁占比和价值、剩余小时数、分配对象 |
classification / technique / returned_funds | hacks | 分类、攻击手法、已追回资金 |
DEX 兑换:/onchain/dex-swaps
仅限 Pro 和 Max 套餐。该端点返回大额兑换数据流,与 DEX Overview 页面相同:每笔兑换会显示它占资金池流动性的比例、预计会造成多大的价格变动,以及 30 秒和 5 分钟后的情况。响应结构见文档。
| 参数 | 类型 | 作用 |
|---|---|---|
period | string | live 为最近 15 分钟,默认值;1h、6h、24h 或 7d |
chain | string | 网络 |
side | string | buy 或 sell |
dex | string | DEX;多个用逗号分隔 |
min_usd | number | 兑换最小金额,USD |
min_impact | number | 资金池影响的最小绝对值,% |
final | boolean | true 表示仅返回已验证的兑换 |
token | string | 代币代码 |
q | string | 在代币、名称、地址、交易者、哈希、DEX 和网络中搜索 |
| 字段 | 类型 | 含义 |
|---|---|---|
id | string | 稳定标识符:网络、交易、代币 |
tier | string | 按资金池流动性划分的层级:从 T1(30,000–100,000 $)到 T4(超过 1000 万 $) |
pool_liquidity_usd / size_pct_liquidity / impact_est_pct | number 或 null | 资金池流动性、该兑换占其比例以及预计价格影响,% |
price_after_30s_usd / price_after_5m_usd / move_after_5m_pct | number 或 null | 30 秒和 5 分钟后的价格,以及兑换后 5 分钟内的价格变动 |
facts | string | 验证状态:pending、publish、30s、final 或 unavailable |
trader_name / trader_address | string 或 null | 交易者标签和地址 |
在下面的示例中,一笔 412,500 $ 的兑换发生在流动性为 4,120,000 $ 的资金池中,占该池的 412,500 / 4,120,000 × 100 = 10.01%。预计影响为 4.8%,5 分钟后价格变动了 1.9%。
curl -G "https://api.genesisarbitrage.com/v1/onchain/dex-swaps" \
-d period=1h -d min_usd=100000 -d final=true \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"id": "ethereum:0x5f3c…e1:0x6982…1933",
"ts": 1794675511,
"token": "PEPE",
"chain": "ethereum",
"side": "buy",
"usd": 412500,
"dex": "Uniswap",
"pool_label": "PEPE/WETH 0.3%",
"tier": "T3",
"pool_liquidity_usd": 4120000,
"size_pct_liquidity": 10.01,
"impact_est_pct": 4.8,
"move_after_5m_pct": 1.9,
"facts": "final",
"explorer_url": "https://etherscan.io/tx/0x5f3c…e1"
}
OnChain 分析:/onchain/analytics
同样仅限 Pro 和 Max。一次调用即可返回 Genesis OnChain Analytics 页面在 period=24h(默认)或 7d 下的内容,包括汇总、按小时分桶数据、交易所资金流、解锁、黑客事件、重点币种和事件流。全部字段见文档。
| 字段 | 类型 | 含义 |
|---|---|---|
kpi | object | 汇总:events、usd、tokens、cex_in、cex_out、cex_net |
hourly | object | 分桶数据,24h 的步长为 1 小时,7d 为 6 小时 |
exchange_flows | object | 按交易所:in_usd、out_usd、net |
tokens | array | 最多 40 个重点币种,附最大事件和 CEX 背景 |
events | array | 该时段的事件流,最多 600 条 |
cex_net 是充币减去提币:示例中 312,456,789 − 287,654,321 = 24,802,468,即流入交易所的资金比流出多 2480 万 $。
curl -G "https://api.genesisarbitrage.com/v1/onchain/analytics" \
-d period=24h \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"period": "24h",
"kpi": {
"events": 1284,
"usd": 912345678,
"tokens": 211,
"cex_in": 312456789,
"cex_out": 287654321,
"cex_net": 24802468
},
"exchange_flows": {
"Binance": {
"in_usd": 98123456, "out_usd": 87654321, "net": 10469135
}
},
"tokens": [ … ],
"events": [ … ]
}
OnChain 币种:/onchain/coin/{symbol}
Pro 和 Max 还可获得单个币种的 7 天摘要,与币种页面相同:链上事件、DEX 兑换、解锁和 CEX 背景。代码放在路径中,长度为 1 到 32 个字符,响应最多每 10 秒重建一次。字段见文档。
| 字段 | 类型 | 含义 |
|---|---|---|
cex | object 或 null | 价格、OI、8 小时资金费率、最佳价差、网络、充币和提币;如果该币不在受支持的 CEX 上则为 null |
kpi | object | 7 天汇总:events、cex_in、cex_out、swaps、dex_buy、dex_sell |
by_section | object | 按板块统计的事件数,键如 large_tx 和 cex_deposits |
events / swaps | array | 事件和兑换,最多 2000 条;完整数量见 events_total 和 swaps_total |
unlocks.upcoming / unlocks.past | array | 即将进行和已经发生的解锁 |
curl "https://api.genesisarbitrage.com/v1/onchain/coin/PEPE" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"symbol": "PEPE",
"cex": {
"price": 0.00001,
"oi_usd": 412000000,
"funding_8h": 0.0081,
"best_spread": 0.42,
"deposit": true,
"withdraw": true,
"nets": ["ETH", "BSC"]
},
"kpi": {
"events": 38, "cex_in": 21000000,
"cex_out": 18500000, "swaps": 54
},
"events_total": 38,
"swaps_total": 54
}
假设示例:通过 cex-flows 查看某币种流入交易所的情况
目标是了解过去一小时内某个币种有多少被转入交易所,并在每笔大额充币时收到通知。在 cex-flows 中,方向体现在标签上:to_name 中出现交易所表示充币,from_name 中出现交易所表示提币。
一小时内,ARB 出现四笔充币:412,000 $、260,000 $、180,000 $ 和 148,000 $,合计 412,000 $ + 260,000 $ + 180,000 $ + 148,000 $ = 1,000,000 $。另有一笔 150,000 $ 的提币。流入交易所的净额为 1,000,000 $ − 150,000 $ = 850,000 $:流入多于流出。第一笔充币的假设数据行如下:
{
"ts": 1794675511,
"token": "ARB",
"chain": "arbitrum_one",
"usd": 412000,
"amount": 1030000,
"from_name": "0x7a2f…c31b",
"to_name": "Binance Deposit",
"tx_hash": "0x9c1e…",
"explorer_url": "https://arbiscan.io/tx/0x9c1e…"
}
设定币种和阈值
coin和min_usd让响应只保留某个币种的大额转账。区分充币和提币
to_name中的交易所表示充币,from_name中的表示提币。按子串匹配标签,忽略大小写。统计时间窗口和新转账
按
ts汇总最近一小时的数据行,仅对新的tx_hash发送通知。按套餐的新鲜度轮询
两次请求之间暂停
meta.freshness_sec秒;遇到429和503时,等待Retry-After秒。
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", 100_000
CEX = ("binance", "okx", "bybit", "coinbase") # 标签子串
seen = set()
def is_cex(label):
return any(name in (label or "").lower() 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()
hour_ago = time.time() - 3600
inflow = outflow = 0.0
for row in body["data"]:
if (row.get("ts") or 0) < hour_ago:
continue
usd = row.get("usd") or 0
if is_cex(row.get("to_name")): # 充币到交易所
inflow += usd
if row.get("tx_hash") not in seen:
seen.add(row.get("tx_hash"))
print(f"{COIN} → {row['to_name']}: ${usd:,.0f}")
elif is_cex(row.get("from_name")): # 提币
outflow += usd
print(f"最近一小时:流入交易所 ${inflow:,.0f},"
f"净流入 ${inflow - outflow:,.0f}")
time.sleep(body["meta"]["freshness_sec"])
该脚本只读取数据并打印通知;如何处置这个币种由您自己决定。流向同一交易所的小额转账系列会归入 coin-traffic 板块,其中的方向已在 direction 字段中给出。所有币种的汇总来自 /onchain/analytics 的 kpi.cex_in、kpi.cex_out 和 kpi.cex_net,链上数据用例的概览见文章链上数据 API。
常见问题
使用链上数据需要哪个套餐?
/onchain/{section} 的九个板块在 Start、Pro 和 Max 上开放。DEX 兑换、分析和币种摘要仅限 Pro 和 Max,在 Trial 上链上端点返回 403 plan_restricted。
有超过 7 天的历史数据吗?
最长的时间窗口是兑换和分析的 period=7d,以及币种摘要中的 7 天;Genesis API 没有单独的归档。需要长期历史时,请在每次轮询时自行保存记录。
为什么某笔兑换从响应中消失了?
验证发现那是流动性调整而不是交易,记录因此被删除。请按 id 匹配已保存的兑换,或只请求 final=true。
如何获取即将到来的代币解锁?
请求 /onchain/unlocks?when=upcoming。每一行都有 unlock_percent 和 unlock_value_usd(解锁的占比和价值),以及 hours_left(距离解锁的剩余小时数)。min_usd 设定价值阈值,coin 选择单个币种。