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
| Endpoint | What it returns | Plans |
|---|---|---|
/arbitrage/spot-spot | Spreads between CEX spot markets | Trial, Start, Pro, Max |
/arbitrage/spot-futures | Spot vs futures on CEX | Trial, Start, Pro, Max |
/arbitrage/futures-futures | Futures across CEX exchanges | Trial, Start, Pro, Max |
/arbitrage/dex-spot | DEX price vs CEX spot | Pro, Max |
/arbitrage/dex-futures | DEX price vs CEX futures | Pro, Max |
/arbitrage/crosschain | One token on DEX across networks | Pro, Max |
/arbitrage/stocks | Tokenized stocks, metals, indices and commodities on CEX | Start, 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.
| Parameter | Type | What it does | Example |
|---|---|---|---|
coin | string | Filter by coin ticker | coin=BTC |
exchange | string | Filter by exchange; comma-separated for several | exchange=Binance,OKX |
min_spread | number | Minimum spread, % | min_spread=1 |
min_volume | number | Minimum 24h volume on both sides, USD | min_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",
…
}
| Field | Type | Contents |
|---|---|---|
exchange_buy, exchange_sell | string | Buy exchange and sell exchange |
market_buy, market_sell | string | The side's market: spot or futures |
price_buy, price_sell | number | Prices the spread is computed from |
bid_*, ask_* | number or null | Best bid and ask on each side |
spread_pct | number | Spread, % |
network, contract | string; string or null | Token network and contract address |
deposit_enabled_*, withdraw_enabled_* | boolean | Whether deposits and withdrawals are open on each exchange |
volume_24h_buy, volume_24h_sell | number or null | 24h volume, USD |
trade_url_buy, trade_url_sell | string | Links 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.
| Parameter | Type | What it does | Example |
|---|---|---|---|
coin | string | Filter by coin ticker | coin=SCR |
exchange | string | CEX exchange; comma-separated for several | exchange=MEXC |
min_spread | number | Minimum spread, % | min_spread=2 |
min_liquidity | number | Minimum liquidity, USD | min_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.
| Field | Type | Contents |
|---|---|---|
exchange | string | CEX exchange |
cex_price, dex_price | number | Price on the CEX and on the DEX |
liquidity_usd | number | Pool liquidity, USD |
market_cap, dex_volume_24h | number or null | Market cap and 24h DEX volume (DEX – Spot) |
ticker, max_position_usd | string; number or null | Exchange pair and maximum position, USD (DEX – Futures) |
deposit_enabled, withdraw_enabled | boolean | Whether deposits and withdrawals are open on the CEX |
dexscreener_url, dextools_url, gmgn_url | string or null | DexScreener, 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.
| Parameter | Type | What it does | Example |
|---|---|---|---|
coin | string | Filter by token ticker | coin=WLD |
chain | string | Filter by network | chain=ethereum |
min_spread | number | Minimum spread, % | min_spread=1 |
min_liquidity | number | Minimum liquidity, USD | min_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,
…
}
}
| Field | Type | Contents |
|---|---|---|
buy.chain | string | The side's network |
buy.pair | string | DEX pair, such as WLD/USDC |
buy.contract | string | Contract address on that network |
buy.price_usd, buy.liquidity_usd, buy.volume_24h_usd | number | Price, pool liquidity and 24h volume, USD |
buy.pool_created_at | string or null | Pool creation date |
buy.dexscreener_url, dextools_url, gmgn_url | string or null | DexScreener, 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.
| Parameter | Type | What it does | Example |
|---|---|---|---|
symbol | string | Filter by instrument ticker | symbol=BRENT |
category | string | Category: Stock, Metal, Index or Commodity | category=Commodity |
exchange | string | Filter by exchange; comma-separated for several | exchange=MEXC |
min_spread | number | Minimum 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:
| Endpoint | Site table and its guide |
|---|---|
/arbitrage/spot-spot | Spot – Spot |
/arbitrage/spot-futures | Spot – Futures |
/arbitrage/futures-futures | Futures Arbitrage |
/arbitrage/dex-spot | DEX – Spot |
/arbitrage/dex-futures | DEX – Futures |
/arbitrage/crosschain | Crosschain |
/arbitrage/stocks | Stock Arbitrage |
How to build a pair monitor
Pick the endpoint for your plan
Check the plans table above: the DEX datasets and Cross-chain are on Pro and Max only.
Narrow the set on the server
Set
min_spreadabove the sum of your fees, andmin_volumeormin_liquidityto drop illiquid coins.Keep executable rows in code
Spot – Spot —
withdraw_enabled_buyanddeposit_enabled_sell. DEX – Spot with a positive spread —deposit_enabled, with a negative one —withdraw_enabled. Stocks — look up bysymbol_on_buyandsymbol_on_sell.Check the token and the order book
Compare
contractandnetwork, and work out the execution for your size with the order book endpoints.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.