Genesis Arbitrage

Genesis Arbitrage · · 12 min read

Genesis API arbitrage endpoints: CEX, DEX, cross-chain and stocks

In short

  • Seven endpoints return the pairs from the site's tables: the three CEX datasets are on every plan, stocks from Start up, and DEX – Spot, DEX – Futures and Cross-chain on Pro and Max.
  • A CEX row carries both exchanges' prices and best quotes, the network, the contract, deposit and withdrawal status and volumes — the fields you use to pick pairs you can actually execute.
  • The spread in a response is the price gap at snapshot time: fees, transfers and slippage are not deducted from it.

Genesis API arbitrage endpoints return the same pairs as the Genesis Arbitrage tables: spreads between CEX spot and futures markets, between DEX and CEX, across networks and on tokenized stocks. Each data item is one pair: where to buy, where to sell, the spread — the price gap in percent — and the fields to check it with: deposit and withdrawal status, volumes, liquidity, links. All seven endpoints are GET requests with the key in the X-API-Key header.

Seven endpoints and plans

EndpointWhat it returnsPlans
/arbitrage/spot-spotSpreads between CEX spot marketsTrial, Start, Pro, Max
/arbitrage/spot-futuresSpot vs futures on CEXTrial, Start, Pro, Max
/arbitrage/futures-futuresFutures across CEX exchangesTrial, Start, Pro, Max
/arbitrage/dex-spotDEX price vs CEX spotPro, Max
/arbitrage/dex-futuresDEX price vs CEX futuresPro, Max
/arbitrage/crosschainOne token on DEX across networksPro, Max
/arbitrage/stocksTokenized stocks, metals, indices and commodities on CEXStart, Pro, Max

An endpoint outside your plan returns 403 plan_restricted; error codes are in Genesis API responses and errors, and prices on the Genesis API pricing page.

CEX: Spot – Spot, Spot – Futures, Futures – Futures

The three CEX endpoints take the same parameters and return rows in the same format. The market_buy and market_sell fields show each side's market: spot and spot, spot and futures, or futures and futures.

ParameterTypeWhat it doesExample
coinstringFilter by coin tickercoin=BTC
exchangestringFilter by exchange; comma-separated for severalexchange=Binance,OKX
min_spreadnumberMinimum spread, %min_spread=1
min_volumenumberMinimum 24h volume on both sides, USDmin_volume=50000
curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot" \
  -d min_spread=1 -d min_volume=50000 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/spot-futures" \
  -d coin=BTC -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/futures-futures" \
  -d exchange=Binance,OKX -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

A response row from the Spot — Spot documentation, shortened:

{
  "coin": "FUEL",
  "exchange_buy": "ByBit",
  "exchange_sell": "Gate",
  "market_buy": "spot",
  "market_sell": "spot",
  "price_buy": 0.0007029,
  "price_sell": 0.0007037,
  "ask_buy": 0.0007029,
  "bid_sell": 0.0007021,
  "spread_pct": 0.11,
  "network": "ETH",
  "contract": "0x675B68AA4d9c2d3BB3F0397048e62E6B7192079c",
  "withdraw_enabled_buy": true,
  "deposit_enabled_sell": true,
  "volume_24h_buy": 17652.64,
  "volume_24h_sell": 12512.51,
  "trade_url_buy": "https://www.bybit.com/trade/spot/FUEL/USDT",
  …
}
FieldTypeContents
exchange_buy, exchange_sellstringBuy exchange and sell exchange
market_buy, market_sellstringThe side's market: spot or futures
price_buy, price_sellnumberPrices the spread is computed from
bid_*, ask_*number or nullBest bid and ask on each side
spread_pctnumberSpread, %
network, contractstring; string or nullToken network and contract address
deposit_enabled_*, withdraw_enabled_*booleanWhether deposits and withdrawals are open on each exchange
volume_24h_buy, volume_24h_sellnumber or null24h volume, USD
trade_url_buy, trade_url_sellstringLinks to the trading terminals

spread_pct is computed from price_buy and price_sell — the Price column on the site, the last trade. The trade itself goes through the order book: you buy at ask_buy and sell at bid_sell. In the example bid_sell is below ask_buy, so at the best quotes the pair is negative:

(0.0007021 − 0.0007029) / 0.0007029 × 100 ≈ −0.11%

The exact gap for your size comes from Order-book Δ — GET /orderbooks/spreads/{dataset}, covered in the order book endpoints guide.

Transferable Spot – Spot pairs

A cross-exchange spot pair works only if the coin can be moved: bought on one exchange, withdrawn and credited on the other. That needs withdrawals open on the buy exchange (withdraw_enabled_buy) and deposits open on the sell exchange (deposit_enabled_sell). The request has no parameters for these flags, so you filter on them in code, while min_volume drops illiquid coins on the server.

import os
import requests

r = requests.get(
    "https://api.genesisarbitrage.com/v1/arbitrage/spot-spot",
    headers={"X-API-Key": os.environ["GENESIS_API_KEY"]},
    params={"min_spread": 1, "min_volume": 50000},
    timeout=15,
)
r.raise_for_status()
rows = r.json()["data"]

# A transfer works only if withdrawals are open on the buy
# exchange and deposits are open on the sell exchange
ok = [x for x in rows
      if x["withdraw_enabled_buy"] and x["deposit_enabled_sell"]]
ok.sort(key=lambda x: x["spread_pct"], reverse=True)

for x in ok[:10]:
    print(f'{x["coin"]:<8} {x["exchange_buy"]} → '
          f'{x["exchange_sell"]} {x["spread_pct"]}% '
          f'network {x["network"]}')

Retries on 429 and 503 come with the get_json function from Genesis API responses and errors. A bot that sends these pairs to Telegram is built in the crypto arbitrage bot in Python article.

DEX – Spot and DEX – Futures

The DEX datasets compare a token's price on a DEX, a decentralized exchange, with its price on a CEX: DEX – Spot against spot, DEX – Futures against futures. Both endpoints are on the Pro and Max plans.

ParameterTypeWhat it doesExample
coinstringFilter by coin tickercoin=SCR
exchangestringCEX exchange; comma-separated for severalexchange=MEXC
min_spreadnumberMinimum spread, %min_spread=2
min_liquiditynumberMinimum liquidity, USDmin_liquidity=50000
curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/dex-spot" \
  -d min_spread=2 -d min_liquidity=50000 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/dex-futures" \
  -d min_spread=1 -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

A DEX – Spot row from the documentation, shortened:

{
  "coin": "SCR",
  "exchange": "MEXC",
  "cex_price": 0.02691,
  "dex_price": 0.02679,
  "spread_pct": 0.45,
  "network": "SCROLL",
  "liquidity_usd": 10544.15,
  "market_cap": 5091835.0,
  "deposit_enabled": true,
  "withdraw_enabled": true,
  "dexscreener_url": "https://dexscreener.com/scroll/0xd296…",
  "dextools_url": null,
  "gmgn_url": null,
  …
}

The MEXC price is above the pool price, so the spread is positive. The sign of spread_pct sets the direction: plus means the token is cheaper on the DEX, so you buy there and sell on the CEX; minus means the opposite.

FieldTypeContents
exchangestringCEX exchange
cex_price, dex_pricenumberPrice on the CEX and on the DEX
liquidity_usdnumberPool liquidity, USD
market_cap, dex_volume_24hnumber or nullMarket cap and 24h DEX volume (DEX – Spot)
ticker, max_position_usdstring; number or nullExchange pair and maximum position, USD (DEX – Futures)
deposit_enabled, withdraw_enabledbooleanWhether deposits and withdrawals are open on the CEX
dexscreener_url, dextools_url, gmgn_urlstring or nullDexScreener, DEXTools and GMGN links

The pool in the example holds $10,544 of liquidity, so a large buy will move its price. Slippage for sizes from $100 to $100,000, token taxes and the honeypot flag per contract come from GET /orderbooks/dex-slippage on the Pro and Max plans.

Cross-chain: one token across networks

GET /arbitrage/crosschain compares one token's DEX price across blockchains, on the Pro and Max plans. A row holds coin, spread_pct and two objects with the same fields: buy, the side where the token is cheaper, and sell, where it costs more. The token moves between networks through a cross-chain bridge.

ParameterTypeWhat it doesExample
coinstringFilter by token tickercoin=WLD
chainstringFilter by networkchain=ethereum
min_spreadnumberMinimum spread, %min_spread=1
min_liquiditynumberMinimum liquidity, USDmin_liquidity=20000
curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/crosschain" \
  -d coin=WLD -d min_liquidity=20000 \
  -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

A row from the Cross-chain documentation, shortened:

{
  "coin": "WLD",
  "spread_pct": 0.59,
  "buy": {
    "chain": "optimism",
    "pair": "WLD/USDC",
    "price_usd": 0.4048,
    "liquidity_usd": 48747,
    "volume_24h_usd": 2484,
    "pool_created_at": "2023-07-24 08:44:19 UTC",
    …
  },
  "sell": {
    "chain": "ethereum",
    "pair": "WLD/WETH",
    "price_usd": 0.4072,
    "liquidity_usd": 421426,
    …
  }
}
FieldTypeContents
buy.chainstringThe side's network
buy.pairstringDEX pair, such as WLD/USDC
buy.contractstringContract address on that network
buy.price_usd, buy.liquidity_usd, buy.volume_24h_usdnumberPrice, pool liquidity and 24h volume, USD
buy.pool_created_atstring or nullPool creation date
buy.dexscreener_url, dextools_url, gmgn_urlstring or nullDexScreener, DEXTools and GMGN links

sell has the same fields. pool_created_at is a UTC date string, not unix seconds like most timestamps in the API, and can be null. A pool created a few days ago is a reason to check the contracts on both sides: a different token may sit behind the same ticker on a new network.

Stock arbitrage: stocks, metals, indices, commodities

GET /arbitrage/stocks returns spreads on tokenized stocks, metals, indices and commodities between CEX exchanges and is available from the Start plan up.

ParameterTypeWhat it doesExample
symbolstringFilter by instrument tickersymbol=BRENT
categorystringCategory: Stock, Metal, Index or Commoditycategory=Commodity
exchangestringFilter by exchange; comma-separated for severalexchange=MEXC
min_spreadnumberMinimum spread, %min_spread=0.3
curl -G --compressed \
  "https://api.genesisarbitrage.com/v1/arbitrage/stocks" \
  -d category=Commodity -H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"

A row from the Stock Arbitrage documentation, shortened:

{
  "symbol": "BRENT",
  "category": "Commodity",
  "exchange_buy": "MEXC",
  "exchange_sell": "Ourbit",
  "symbol_on_buy": "UKOIL",
  "symbol_on_sell": "BRENTOIL",
  "price_buy": 76.68,
  "price_sell": 76.82,
  "spread_pct": 0.18,
  …
}

symbol is the instrument's common ticker, while symbol_on_buy and symbol_on_sell are its names on each exchange: in the example Brent crude trades as UKOIL on MEXC and as BRENTOIL on Ourbit. Look the instrument up on the exchange by symbol_on_*. The row has no network, contract or deposit fields: on CEX these instruments trade as perpetual futures, and the pair is opened with Long and Short positions (table guide).

API responses and site tables

The site table columns are explained in the guides:

EndpointSite table and its guide
/arbitrage/spot-spotSpot – Spot
/arbitrage/spot-futuresSpot – Futures
/arbitrage/futures-futuresFutures Arbitrage
/arbitrage/dex-spotDEX – Spot
/arbitrage/dex-futuresDEX – Futures
/arbitrage/crosschainCrosschain
/arbitrage/stocksStock Arbitrage

How to build a pair monitor

  1. Pick the endpoint for your plan

    Check the plans table above: the DEX datasets and Cross-chain are on Pro and Max only.

  2. Narrow the set on the server

    Set min_spread above the sum of your fees, and min_volume or min_liquidity to drop illiquid coins.

  3. Keep executable rows in code

    Spot – Spot — withdraw_enabled_buy and deposit_enabled_sell. DEX – Spot with a positive spread — deposit_enabled, with a negative one — withdraw_enabled. Stocks — look up by symbol_on_buy and symbol_on_sell.

  4. Check the token and the order book

    Compare contract and network, and work out the execution for your size with the order book endpoints.

  5. Poll at your plan's pace

    No more often than meta.freshness_sec. The bot sends an alert, and you place the trade on the exchange yourself.

Questions and answers

Can these endpoints place a trade?

No. Genesis API only serves data and places no orders. A bot on Genesis API finds a pair and sends you an alert, and you open the trade on the exchange yourself.

Why do rows have no Book or Ord. columns?

Both are computed from order books and come separately: Order-book Δ from GET /orderbooks/spreads/{dataset} and a market's order book from GET /orderbooks/book, both on the Pro and Max plans.

Which plan do I need for DEX and Cross-chain?

Pro or Max. Trial covers the three CEX datasets, and Start adds stock arbitrage.