Genesis Arbitrage

Genesis Arbitrage · · 14 min read

On-chain data API: whale transfers, exchange flows and token unlocks

In short

  • An on-chain data API returns blockchain events already decoded: which token moved, from whom, to whom and for how many dollars. Raw data comes from nodes, indexers turn it into tables, and address labels remain attribution that can be wrong.
  • Traders watch exchange deposits and withdrawals, large transfers, team wallet moves, perp DEX positions, unlocks, claims, hacks and large DEX swaps. A deposit to an exchange doesn't always end in a sale.
  • In Genesis API the nine on-chain sections are available from the Start plan, while DEX swaps, analytics and the coin summary need Pro or Max. Your code computes the window and the flow totals, since the sections have no time parameter.

An on-chain data API is an HTTP interface to blockchain events that have already been collected, converted to dollars and labeled: which token moved, from which address, to which address and in which transaction. With such an API you can track whale transfers, exchange inflows, token unlocks and large swaps on a DEX without running your own node or indexer. A whale here is an address holding enough of a coin for its transfers to move the market.

Where on-chain data comes from

The data passes through three layers: a node stores blocks, an indexer turns them into event rows, and a label database names the addresses.

Node: blocks and logs

A blockchain node stores blocks and serves them over JSON-RPC. On Ethereum and compatible chains, an ERC-20 token transfer is written to the transaction log as the Transfer(address indexed _from, address indexed _to, uint256 _value) event, and the standard recommends emitting the same event with 0x0 as the sender when new tokens are minted (EIP-20).

The eth_getLogs method returns logs that match a filter: a block range fromBlock and toBlock, a contract address and event topics (Ethereum JSON-RPC). A log holds addresses, the block number, the transaction hash and the amount in the token's smallest units. The block has no dollar price, no owner name and no exchange flag.

Indexer: from logs to tables

An indexer reads blocks in order, decodes events and sorts them into tables: transfers, swaps, pool changes. It divides the amount by 10 to the power of the token's decimals (with eight decimals, that means dividing by 100,000,000) and multiplies it by the price at block time, which gives the dollar value.

Then come thresholds: the feed keeps transfers above a set amount, and series of small transfers to one address are merged into one row. Running such a pipeline for several chains is a project of its own, and an on-chain data API returns its output in one request.

Address labels: who is behind an address

A label is a name attached to an address: "Binance", "project treasury", "market maker". It is assigned from evidence: the address forwards coins to a known exchange wallet, the project published its addresses itself, the address received tokens from a vesting contract. The owner confirms none of this, so a label can be outdated or simply wrong.

An address with no evidence stays unnamed: in the Genesis API documentation examples, such a sender shows a shortened address, 0xec01…d1a5.

Which on-chain events matter to traders

A hypothetical example: over one morning, $2,000,000 of a project's coin went to exchanges, and $500,000 left its team wallet for a market maker's address. Each event alone says little; together they are a reason to check the price, open interest and the unlock schedule.

EventWhat you seeHow it's usually read
Exchange depositCoins arrive at an exchange addressPossible sale, collateral or a reshuffle
Exchange withdrawalCoins leave for an external addressStorage, DeFi or another exchange
Large transferA transfer above the threshold between addressesA whale moves its position
Team walletMoves from foundation, treasury or founder addressesA deposit to an exchange weighs more than an internal move
Perp DEX positionLong or short: size, price, venueA whale's bet and liquidation risk
UnlockDate, share and value of the releaseNew supply of the coin
ClaimTokens from an airdrop, vesting, rewardsRecipients can sell right away
Mint and bridgeToken issuance, moves between chainsStablecoin minting means money coming in
HackProtocol, losses, attack techniqueRisk for the token and connected chains
DEX swapSide, amount, pool share, price movePrice shift before exchanges react

Positions on decentralized exchanges for perpetual futures, perp DEXes, are visible because these venues keep their data open. On Hyperliquid, the info endpoint POST https://api.hyperliquid.xyz/info with a clearinghouseState request returns the open positions and margin of any address, with no key (Hyperliquid docs). CEXes don't publish other traders' positions; they give aggregate figures such as open interest.

An unlock is the release of team, investor or foundation tokens under a vesting schedule, which hands them out in tranches on a set timetable. The date is known in advance, so the market may price in the selling before the event.

A DEX swap moves the pool price in the same block. A hypothetical example: a $150,000 buy in a pool with $1,200,000 of liquidity takes 150,000 / 1,200,000 × 100 = 12.5% of the pool. The pool price moves noticeably, while on exchanges the move shows up later or not at all. DEX and CEX prices are compared in the DEX API article.

A hack shows up on-chain as transfers out of a protocol's contract. Bridges get attacked more often than other protocols because their contracts hold large sums: notable cases are in the blockchain bridges article, and a theft from an exchange in the Bybit hack breakdown.

Latency and confirmation

Seconds to minutes pass between a transaction and a row in your code; this is data latency. It hardly matters for a daily flow overview, but it decides the outcome when you react to one large deposit or swap.

Network confirmation

On Ethereum a new block can appear once per slot, every 12 seconds, and it becomes final after about 15 minutes (ethereum.org). A finalized block can't be changed unless a huge amount of ETH is lost. An indexer that needs only the settled picture can read blocks up to the finalized tag, which is how a node names the latest finalized block.

An exchange credits a deposit once the transaction reaches a minimum number of network confirmations, and at Binance, for example, that minimum differs for each coin (Binance FAQ). So a deposit to an exchange is visible on-chain before the owner can sell those coins.

Data delay

In the swap example from the Genesis API documentation, ts = 1794675511 is the swap time and published_at = 1794675523 is the publication time: 1794675523 − 1794675511 = 12 seconds apart. On top of that come your plan's data freshness in meta.freshness_sec (30 seconds on Start, 10 on Pro, 5 on Max) and your polling interval.

StageHow longWhat it means
Ethereum block12 s slotThe transaction is visible but not final
Ethereum finalityabout 15 minThe block won't change anymore
Exchange creditingthe exchange's confirmation minimumDifferent for each coin
Swap publication12 s in the exampleThe record isn't final yet
final statusno earlier than 5 min after the swapThe price after 30 s and 5 min is known
Genesis API delivery30, 10 or 5 sStart, Pro and Max plans

For swaps, the period=live feed with unverified records is faster, but a record can disappear if the swap turns out to be a liquidity reshuffle. The final=true parameter keeps only verified swaps, which arrive at least 5 minutes later.

On-chain data in Genesis API

Genesis API returns the feeds of the Genesis OnChain section: transfer rows already carry sender and receiver labels, the amount in dollars and in tokens, the transaction hash and an explorer link. Requests are HTTP GET with the key in the X-API-Key header, and the response is JSON with a data field and a meta block.

EndpointWhat it returnsPlans
/onchain/{section}One of the 9 on-chain sectionsStart, Pro, Max
/onchainAll 9 sections in one objectStart, Pro, Max
/onchain/dex-swapsLarge DEX swapsPro, Max
/onchain/analyticsTotals for 24h or 7dPro, Max
/onchain/coin/{symbol}A 7-day coin summaryPro, Max

The sections are named after the feeds: large-transfers, cex-flows, mint-bridge, team-wallets, perp-positions, unlocks, claims, hacks and coin-traffic, which holds series of transfers of one coin to one target. The filters are min_usd and coin, plus when with upcoming or past for unlocks. There is no time parameter, so the window is computed from the ts field.

A request for upcoming token unlocks worth more than $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"

An unlock row has unlock_percent and unlock_value_usd (share and value), hours_left (hours until the event) and allocations (breakdown by recipient).

Pro and Max add three endpoints. /onchain/dex-swaps returns large swaps with the pool liquidity share, the estimated price impact and the price move after 30 seconds and 5 minutes (DEX overview in the docs). /onchain/analytics computes totals for 24h or 7d: kpi.cex_in, kpi.cex_out, kpi.cex_net and flows per exchange (OnChain analytics). /onchain/coin/{symbol} collects a coin's events, swaps and unlocks over 7 days together with its CEX price, OI and funding (OnChain coin).

Only a 200 response uses quota, and on Trial the on-chain endpoints return 403 plan_restricted. Start costs $50 a month for 2M calls, Pro $100 for 5M, Max $200 for 10M (Genesis API pricing). Every parameter and field, with response examples, is in the on-chain endpoints guide.

Without code, the same feeds are on the Genesis OnChain dashboard, swaps in the DEX Overview, and daily and weekly totals in OnChain Analytics.

Python: a coin's exchange deposits over a window

A hypothetical example: over 6 hours, five ARB transfers reached exchanges, for $640,000, $520,000, $410,000, $330,000 and $150,000. The total is 640,000 + 520,000 + 410,000 + 330,000 + 150,000 = 2,050,000, so the $2,000,000 threshold is crossed. Once the first transfer is older than 6 hours, it drops out of the window: 2,050,000 − 640,000 = 1,410,000, and the total falls below the threshold again.

cex-flows has no direction field, so the direction comes from the labels: an exchange in to_name is a deposit, an exchange in from_name is a withdrawal. The response is the section's current feed, so the script keeps deposits by tx_hash and drops old ones itself. That way the window total isn't double-counted across polls.

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        # window, seconds
ALERT_USD = 2_000_000    # deposit total that triggers an alert
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):  # rate limit or rebuild
        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}: to exchanges in 6 h ${total:,.0f}, "
          f"transfers {len(deposits)}")
    if total >= ALERT_USD and not alerted:
        print("Threshold crossed: check price, OI and funding")
    alerted = total >= ALERT_USD
    time.sleep(body["meta"]["freshness_sec"])

The CEX tuple holds label substrings; add the exchanges where the coin trades. The script only counts and prints: Genesis API places no orders, and the trading decision stays with you.

A response to a request with coin and min_usd comes without an ETag, so every poll uses a call. On Start the pause is 30 seconds, which is 2,592,000 / 30 = 86,400 calls over 30 days, or 4.32% of the 2M quota. For a dozen coins, fetch the /onchain/cex-flows feed without filters and split it yourself: the full set comes with an ETag, and a repeat with If-None-Match on unchanged data returns 304 without using quota.

Transfers below min_usd won't be counted: series of small transfers of one coin to one exchange are grouped in coin-traffic, with the direction, total_usd, count and window_hours fields.

How to read an exchange deposit

The same $2,050,000 of ARB that reached exchanges over 6 hours could be preparation for a sale, collateral for futures or a move between the owner's own accounts. One feed row won't tell you which.

ScenarioWhat else you seeHow to check
Preparing to sellDEX sells, the price weakens/onchain/dex-swaps with side=sell
Futures collateralOpen interest grows, funding changes/market/open-interest, /funding/rates
Internal reshuffleA matching withdrawal from the same exchangefrom_name in cex-flows, the explorer
Team or fund sellingThe sender is a team walletteam-wallets, unlocks

Several events on one coin carry more weight than a single one: an exchange deposit, a transfer from the team wallet and an upcoming unlock. You can see them in one /onchain/coin/{symbol} response, where the events sit next to the cex block with oi_usd and funding_8h. The /market/open-interest and /funding/rates endpoints from the table are available from Trial.

Other market data and how to pick a source for a task are covered in the crypto API overview.

Questions and answers

How accurate are address labels in on-chain data?

Labels are assigned from evidence and the address owner doesn't confirm them, so full accuracy isn't possible. The more transfers link an address to a known wallet, the more reliable the conclusion, and new addresses more often stay unnamed. Check any large event via the explorer link.

Does Genesis API have on-chain history?

There is no deep archive. The longest windows are 7 days: period=7d for swaps and analytics and the 7-day coin summary, while past unlocks come from when=past. Build long history yourself by saving records on every poll by tx_hash or id.

What do the pending and final statuses mean for DEX swaps?

It's the facts field, the record's verification status. pending means the swap is published and the price after it is still awaited; publish and 30s are intermediate stages; final means the record is verified and the price after 30 seconds and 5 minutes is known; unavailable means the facts couldn't be collected. Until the status is final, a record can disappear, so store swaps by id or request final=true.

Can I track whales with an API for free?

You can take raw data from your own node or a public endpoint over JSON-RPC, but labels, dollar amounts and thresholds are then yours to build. Genesis API has no free plan: the on-chain sections start with the Start plan at $50 a month, DEX swaps and analytics with Pro at $100.