Genesis Arbitrage

Genesis Arbitrage · · 12 min read

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

EndpointWhat it returnsAPI plans
/onchain/{section}One of the nine Genesis OnChain sectionsStart, Pro, Max
/onchainAll nine sections in one objectStart, Pro, Max
/onchain/dex-swapsLarge DEX swapsPro, Max
/onchain/analyticsOnChain analytics for 24h or 7dPro, Max
/onchain/coin/{symbol}A 7-day summary of one coinPro, 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}

sectionWhat's insideDashboard block
large-transfersLarge token transfersLarge Transfers
cex-flowsDeposits to and withdrawals from exchangesCEX Deposits / Withdrawals
mint-bridgeToken minting and bridge transfersMint / Bridge
team-walletsTeam wallet movementsTeam Transfers
perp-positionsLarge positions on perp DEXesPerp. DEX Positions
unlocksToken unlocksUnlocks
claimsClaimsClaims
coin-trafficSeries of transfers of one coin to one targetCoin Traffic
hacksHacks and exploitsHacks / 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.

ParameterTypeWhat it does
min_usdnumberMinimum event amount, USD
coinstringRows of one coin; hacks have no coin, so the list comes back empty
whenstringFor unlocks only: upcoming or past
sectionstringSection 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.

FieldsWhereMeaning
ts, linksAll sectionsEvent time in unix seconds and ready links text + url
token / token_nameTransfers, coin-trafficToken ticker and full name
chain / chain_name, usd / amountTransfersNetwork, amount in USD and in tokens
from_* / to_*TransfersSender and receiver: label, address, explorer link
tx_hash / explorer_url / arkham_urlTransfersTransaction hash, explorer and Arkham links
direction, target / target_addresscoin-trafficDirection deposit, withdrawal or transfer and the flow target
total_usd / count / window_hours, transfers[]coin-trafficSeries total, transfer count, window in hours and the largest transfers
side / size / price / platformperp-positionsLong or Short, size, price, venue
unlock_percent / unlock_value_usd / hours_left / allocationsunlocksUnlock share and value, hours left, allocations
classification / technique / returned_fundshacksClassification, 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.

ParameterTypeWhat it does
periodstringlive — the last 15 minutes, default; 1h, 6h, 24h or 7d
chainstringNetwork
sidestringbuy or sell
dexstringDEX; comma-separated for several
min_usdnumberMinimum swap amount, USD
min_impactnumberMinimum absolute pool impact, %
finalbooleantrue — verified swaps only
tokenstringToken ticker
qstringSearch across token, name, addresses, trader, hash, DEX and network
FieldTypeMeaning
idstringStable identifier: chain, transaction, token
tierstringTier by pool liquidity: from T1 ($30,000–100,000) to T4 (over $10M)
pool_liquidity_usd / size_pct_liquidity / impact_est_pctnumber or nullPool liquidity, the swap's share of it and the estimated price impact, %
price_after_30s_usd / price_after_5m_usd / move_after_5m_pctnumber or nullPrice after 30 s and 5 min and the price move over 5 minutes after the swap
factsstringVerification status: pending, publish, 30s, final or unavailable
trader_name / trader_addressstring or nullTrader 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.

FieldTypeMeaning
kpiobjectTotals: events, usd, tokens, cex_in, cex_out, cex_net
hourlyobjectBuckets with a 1 h step for 24h and 6 h for 7d
exchange_flowsobjectPer exchange: in_usd, out_usd, net
tokensarrayUp to 40 coins in focus with the largest event and CEX context
eventsarrayThe 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.

FieldTypeMeaning
cexobject or nullPrice, OI, 8-hour funding, best spread, networks, deposit and withdrawal; null if the coin isn't on supported CEXes
kpiobject7-day totals: events, cex_in, cex_out, swaps, dex_buy, dex_sell
by_sectionobjectEvent counts by section, with keys such as large_tx and cex_deposits
events / swapsarrayEvents and swaps, up to 2000; full counts in events_total and swaps_total
unlocks.upcoming / unlocks.pastarrayUpcoming 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…"
}
  1. Set the coin and threshold

    coin and min_usd keep large transfers of one coin in the response.

  2. Separate deposits from withdrawals

    An exchange in to_name is a deposit, in from_name a withdrawal. Match labels by substring, ignoring case.

  3. Count the window and new transfers

    Sum the rows of the last hour by ts, and notify only on new tx_hash values.

  4. Poll at your plan's freshness

    Pause for meta.freshness_sec between requests; on 429 and 503, wait Retry-After seconds.

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.