Genesis API on-chain data: transfers, flows, unlocks, DEX swaps
In short
- The /onchain/{section} endpoint returns any of the nine Genesis OnChain feeds, from large transfers to hacks, on the Start, Pro and Max plans. A request to /onchain without a section returns every feed in one object.
- Large DEX swaps, 24-hour or 7-day analytics and a 7-day coin summary are available on the Pro and Max plans.
- Address labels are attribution, not a guarantee. A transfer to an exchange doesn't always mean a sale, and a swap record can disappear after verification.
Genesis API on-chain endpoints return the data of the Genesis OnChain section: large token transfers, exchange deposits and withdrawals, team wallet movements, perp DEX positions, token unlocks, claims and hacks, plus large swaps on DEX. Every row already carries sender and receiver labels, the USD amount and explorer links. This is enough for whale tracking and exchange-flow monitoring from your own code, with no blockchain indexer of your own.
Endpoints and plans
| Endpoint | What it returns | API plans |
|---|---|---|
/onchain/{section} | One of the nine Genesis OnChain sections | Start, Pro, Max |
/onchain | All nine sections in one object | Start, Pro, Max |
/onchain/dex-swaps | Large DEX swaps | Pro, Max |
/onchain/analytics | OnChain analytics for 24h or 7d | Pro, Max |
/onchain/coin/{symbol} | A 7-day summary of one coin | Pro, Max |
On Trial, every on-chain endpoint returns 403 plan_restricted. Freshness is 30 s on Start, 10 s on Pro and 5 s on Max, and the same value arrives in meta.freshness_sec. The key and the first request are covered in the quick start, quotas in Genesis API limits.
Nine sections of /onchain/{section}
section | What's inside | Dashboard block |
|---|---|---|
large-transfers | Large token transfers | Large Transfers |
cex-flows | Deposits to and withdrawals from exchanges | CEX Deposits / Withdrawals |
mint-bridge | Token minting and bridge transfers | Mint / Bridge |
team-wallets | Team wallet movements | Team Transfers |
perp-positions | Large positions on perp DEXes | Perp. DEX Positions |
unlocks | Token unlocks | Unlocks |
claims | Claims | Claims |
coin-traffic | Series of transfers of one coin to one target | Coin Traffic |
hacks | Hacks and exploits | Hacks / Exploits |
What each block shows and which signals to look for is covered in the Genesis OnChain dashboard guide, the parameters in the documentation. A request to /onchain without a section returns an object in data: the key is the section name, the value is its rows. Filters then apply to every section.
| Parameter | Type | What it does |
|---|---|---|
min_usd | number | Minimum event amount, USD |
coin | string | Rows of one coin; hacks have no coin, so the list comes back empty |
when | string | For unlocks only: upcoming or past |
section | string | Section for a /onchain?section=… request |
Any other when value returns 400 bad_request. Below is the coin-traffic section, one item of the data array:
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",
…
}
]
}
Section fields
The large-transfers, cex-flows, mint-bridge, team-wallets and claims sections are made of transfers; the others have their own fields.
| Fields | Where | Meaning |
|---|---|---|
ts, links | All sections | Event time in unix seconds and ready links text + url |
token / token_name | Transfers, coin-traffic | Token ticker and full name |
chain / chain_name, usd / amount | Transfers | Network, amount in USD and in tokens |
from_* / to_* | Transfers | Sender and receiver: label, address, explorer link |
tx_hash / explorer_url / arkham_url | Transfers | Transaction hash, explorer and Arkham links |
direction, target / target_address | coin-traffic | Direction deposit, withdrawal or transfer and the flow target |
total_usd / count / window_hours, transfers[] | coin-traffic | Series total, transfer count, window in hours and the largest transfers |
side / size / price / platform | perp-positions | Long or Short, size, price, venue |
unlock_percent / unlock_value_usd / hours_left / allocations | unlocks | Unlock share and value, hours left, allocations |
classification / technique / returned_funds | hacks | Classification, attack technique, returned funds |
DEX swaps: /onchain/dex-swaps
Pro and Max plans. The endpoint returns the feed of large swaps, like the DEX Overview screen: each swap shows what share of the pool's liquidity it took, what price move to expect from it and what happened after 30 seconds and 5 minutes. The response schema is in the documentation.
| Parameter | Type | What it does |
|---|---|---|
period | string | live — the last 15 minutes, default; 1h, 6h, 24h or 7d |
chain | string | Network |
side | string | buy or sell |
dex | string | DEX; comma-separated for several |
min_usd | number | Minimum swap amount, USD |
min_impact | number | Minimum absolute pool impact, % |
final | boolean | true — verified swaps only |
token | string | Token ticker |
q | string | Search across token, name, addresses, trader, hash, DEX and network |
| Field | Type | Meaning |
|---|---|---|
id | string | Stable identifier: chain, transaction, token |
tier | string | Tier by pool liquidity: from T1 ($30,000–100,000) to T4 (over $10M) |
pool_liquidity_usd / size_pct_liquidity / impact_est_pct | number or null | Pool liquidity, the swap's share of it and the estimated price impact, % |
price_after_30s_usd / price_after_5m_usd / move_after_5m_pct | number or null | Price after 30 s and 5 min and the price move over 5 minutes after the swap |
facts | string | Verification status: pending, publish, 30s, final or unavailable |
trader_name / trader_address | string or null | Trader label and address |
In the example below, a $412,500 swap in a pool with $4,120,000 of liquidity took 412,500 / 4,120,000 × 100 = 10.01% of the pool. The estimated impact is 4.8%, and after 5 minutes the price had moved 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 analytics: /onchain/analytics
Also Pro and Max. One call returns the Genesis OnChain Analytics screen for period=24h (the default) or 7d, with totals, hourly buckets, exchange flows, unlocks, hacks, coins in focus and the event feed. All fields are in the documentation.
| Field | Type | Meaning |
|---|---|---|
kpi | object | Totals: events, usd, tokens, cex_in, cex_out, cex_net |
hourly | object | Buckets with a 1 h step for 24h and 6 h for 7d |
exchange_flows | object | Per exchange: in_usd, out_usd, net |
tokens | array | Up to 40 coins in focus with the largest event and CEX context |
events | array | The period's event feed, up to 600 |
cex_net is deposits minus withdrawals: in the example 312,456,789 − 287,654,321 = 24,802,468, so $24.8M more went onto exchanges than came off them.
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 coin: /onchain/coin/{symbol}
Pro and Max also get a 7-day summary of one coin, like the coin page: on-chain events, DEX swaps, unlocks and CEX context. The ticker goes in the path, 1 to 32 characters, and the response is rebuilt at most once every 10 seconds. Fields are in the documentation.
| Field | Type | Meaning |
|---|---|---|
cex | object or null | Price, OI, 8-hour funding, best spread, networks, deposit and withdrawal; null if the coin isn't on supported CEXes |
kpi | object | 7-day totals: events, cex_in, cex_out, swaps, dex_buy, dex_sell |
by_section | object | Event counts by section, with keys such as large_tx and cex_deposits |
events / swaps | array | Events and swaps, up to 2000; full counts in events_total and swaps_total |
unlocks.upcoming / unlocks.past | array | Upcoming and past unlocks |
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
}
Hypothetical example: a coin's deposits to exchanges via cex-flows
The goal is to know how much of a coin was moved onto exchanges over the last hour and to get a notification for every large deposit. In cex-flows the direction shows in the labels: an exchange in to_name means a deposit, an exchange in from_name means a withdrawal.
Over an hour, ARB saw four deposits: $412,000, $260,000, $180,000 and $148,000, for a total of $412,000 + $260,000 + $180,000 + $148,000 = $1,000,000. There was one withdrawal of $150,000. The net flow to exchanges is $1,000,000 − $150,000 = $850,000: more is coming in than going out. This is what the hypothetical row of the first deposit looks like:
{
"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…"
}
Set the coin and threshold
coinandmin_usdkeep large transfers of one coin in the response.Separate deposits from withdrawals
An exchange in
to_nameis a deposit, infrom_namea withdrawal. Match labels by substring, ignoring case.Count the window and new transfers
Sum the rows of the last hour by
ts, and notify only on newtx_hashvalues.Poll at your plan's freshness
Pause for
meta.freshness_secbetween requests; on429and503, waitRetry-Afterseconds.
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") # label substrings
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): # rate limit or rebuild
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")): # deposit to an exchange
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")): # withdrawal
outflow += usd
print(f"last hour: to exchanges ${inflow:,.0f}, "
f"net flow ${inflow - outflow:,.0f}")
time.sleep(body["meta"]["freshness_sec"])
The script only reads data and prints notifications; what to do with the coin is your decision. Series of small transfers to one exchange are grouped in the coin-traffic section, where the direction is already in the direction field. Totals across all coins come from /onchain/analytics in kpi.cex_in, kpi.cex_out and kpi.cex_net, and an overview of on-chain data use cases is in the on-chain data API article.
Questions and answers
Which plan do I need for on-chain data?
The nine /onchain/{section} sections are open on Start, Pro and Max. DEX swaps, analytics and the coin summary are Pro and Max only, and on Trial the on-chain endpoints return 403 plan_restricted.
Is there history beyond 7 days?
The longest windows are period=7d for swaps and analytics and 7 days in the coin summary; Genesis API has no separate archive. For long history, store the records yourself on every poll.
Why did a swap disappear from the response?
Verification found a liquidity reshuffle instead of a trade, and the record was removed. Match saved swaps by id or request only final=true.
How do I get upcoming token unlocks?
Request /onchain/unlocks?when=upcoming. Each row has unlock_percent and unlock_value_usd, the unlock's share and value, and hours_left, the hours remaining until it. min_usd sets a value threshold, coin picks one coin.