Endpoints de order book da Genesis API: preço de execução, Δ do order book, livro, histórico e DEX
Em resumo
- Seis endpoints de order book nos planos API Pro e Max retornam os mesmos dados que o site mostra na coluna «Δ por ordens», na janela «Order book» e no Genesis Charts.
- O preço de execução é o preço médio de uma operação a mercado de US$ 500, 1.000, 2.500, 5.000 ou 10.000;
nullsignifica que o livro é raso demais para esse volume. - Os livros atrasam de 5 a 20 segundos em relação à exchange: confira
age_secestale, e veja o livro no terminal da exchange antes de operar.
A API de order book da Genesis API reúne seis endpoints que mostram quanto de um spread sobrevive a uma operação de determinado tamanho. Eles retornam preços de execução para um volume, o Δ do order book para linhas de arbitragem, um livro de ofertas com sua profundidade, o histórico de slippage e o slippage em DEX — os mesmos dados da coluna «Δ por ordens» e do Genesis Charts no site.
Seis endpoints de order book
| Endpoint | O que retorna | Obrigatório | Documentação |
|---|---|---|---|
/orderbooks/exec | Preços de compra e venda para um volume em cada mercado | volume | Preços de execução |
/orderbooks/spreads/{dataset} | Δ do order book para as linhas de uma moeda em um dataset de arbitragem | coin | Δ do order book |
/orderbooks/book | Livro de um mercado: 10 níveis, paredes, profundidade, idade | exchange, market, coin | Order book do mercado |
/orderbooks/coin/{coin} | Livros de uma moeda em todas as exchanges e mercados | moeda no caminho | Order books da moeda |
/orderbooks/exec-history | Histórico de slippage, até 8 mercados por requisição | keys, interval | Histórico de execução |
/orderbooks/dex-slippage | Slippage, taxas e flag de honeypot por contrato | — | Slippage em DEX |
Os seis fazem parte dos planos da API Pro (US$ 100 por mês) e Max (US$ 200); no Trial e no Start retornam 403 plan_restricted. Em /orderbooks/exec e no parâmetro keys do histórico, um mercado é escrito como Exchange|market|COIN, por exemplo Binance|spot|BTC. Os exemplos de resposta abaixo mostram o campo data, abreviado.
Para uma visão geral dos dados de order book, veja o artigo sobre a API de order book.
Preço de execução para um volume
O preço de execução é o preço médio pelo qual uma ordem a mercado de determinado tamanho percorre o livro: a compra consome os asks, a venda atinge os bids, então é o VWAP das ordens que a operação consome. /orderbooks/exec o retorna para todos os mercados, para um volume da grade.
| Parâmetro | Tipo | O que faz |
|---|---|---|
volume | número | Volume em USD: 500, 1000, 2500, 5000 ou 10000, obrigatório |
exchange | string | Filtra por exchange; separadas por vírgula para várias |
market | string | spot ou futures |
coin | string | Ticker da moeda, p. ex. BTC |
curl "https://api.genesisarbitrage.com/v1/orderbooks/exec?volume=1000" \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"volume": 1000,
"markets": {
"Binance|spot|BTC": [96021.5, 96010.2],
"ByBit|futures|BTC": [96030.1, 96018.7],
"Ourbit|spot|SHELL": [0.10418, null],
…
}
}
O valor de cada chave de mercado é [preço de compra, preço de venda]. null no lugar de um preço significa que o livro é raso demais para esse volume: no exemplo, os bids de SHELL na Ourbit não absorvem uma venda de US$ 1.000. Sem filtros a resposta traz todos os mercados, então passe coin quando precisar de uma moeda só.
Δ do order book: o spread depois de percorrer o livro
O Δ do order book é o spread de uma linha de arbitragem recalculado pelos livros para um volume dado. /orderbooks/spreads/{dataset} pega todas as linhas de uma moeda no dataset escolhido e adiciona a cada uma um objeto order_delta, com as mesmas fórmulas da coluna do site.
| Parâmetro | Tipo | O que faz |
|---|---|---|
{dataset} | string, no caminho | spot-spot, spot-futures, futures-futures, dex-spot ou dex-futures |
coin | string | Ticker da moeda, obrigatório |
volume | número | 0 por padrão — melhores preços do livro; ou 500, 1000, 2500, 5000, 10000 |
Nos pares CEX, a compra percorre os asks de exchange_buy e a venda entra nos bids de exchange_sell. order_delta traz buy_price e sell_price, e o resultado nunca passa do spread_pct da linha.
Nas linhas DEX, o sinal do spread define o lado CEX: com spread_pct ≥ 0 o token é vendido nos bids da CEX; com spread negativo, é comprado nos asks. order_delta traz side e cex_price, o preço de execução na CEX; se o sinal inverte depois de percorrer o livro, o Δ é 0.
O campo status: ok — calculado, no_book — sem livro, exhausted — o livro não preencheu o volume.
Um exemplo hipotético: moeda XYZ, compra na MEXC a 2,000, venda na Gate a 2,016, spread da linha 0,8%. Requisição do Δ do order book para US$ 5.000:
curl -G \
"https://api.genesisarbitrage.com/v1/orderbooks/spreads/spot-spot" \
-d coin=XYZ -d volume=5000 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"coin": "XYZ",
"exchange_buy": "MEXC",
"exchange_sell": "Gate",
"market_buy": "spot",
"market_sell": "spot",
"price_buy": 2.0,
"price_sell": 2.016,
"ask_buy": 2.001,
"bid_sell": 2.015,
"spread_pct": 0.8,
"order_delta": {
"volume": 5000,
"buy_price": 2.004,
"sell_price": 2.01,
"spread_pct": 0.2994,
"status": "ok"
}
}
Os demais campos da linha são como em /arbitrage/spot-spot. Spread da linha: (2,016 − 2,000) / 2,000 × 100 = 0,8%.
Para US$ 5.000, comprar pelo livro da MEXC dá média de 2,004 e vender no livro da Gate rende 2,010: (2,010 − 2,004) / 2,004 × 100 ≈ 0,2994%. Dos 0,8%, cerca de 0,3% sobrevive nesse tamanho — uns US$ 15 antes das taxas e da transferência: 5.000 × 0,002994 ≈ 14,97.
Exemplo em Python: spread antes e depois do livro
O script imprime o spread da linha ao lado do spread depois do livro para BTC no dataset Spot – Spot com US$ 5.000. A chave vem da variável de ambiente GENESIS_API_KEY; em 429 e 503 o script espera Retry-After segundos.
import os
import time
import requests
BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
def get(path, params):
for _ in range(3):
r = requests.get(BASE + path, headers=HEADERS,
params=params, timeout=15)
if r.status_code in (429, 503):
# limite de requisições ou dados sendo reconstruídos
time.sleep(int(r.headers.get("Retry-After", "5")))
continue
r.raise_for_status()
return r.json()["data"]
raise RuntimeError("API ocupada, tente novamente mais tarde")
rows = get("/orderbooks/spreads/spot-spot",
{"coin": "BTC", "volume": 5000})
for row in rows:
od = row["order_delta"]
if od["status"] == "ok":
after = f'{od["spread_pct"]:.4f}%'
else:
after = od["status"] # no_book ou exhausted
print(f'{row["exchange_buy"]} → {row["exchange_sell"]}: '
f'{row["spread_pct"]}% → {after}')
Em um loop, consulte no máximo uma vez a cada meta.freshness_sec segundos: 10 s no Pro, 5 s no Max. A cota e os limites estão no guia de limites da Genesis API.
Order book do mercado e order books da moeda
/orderbooks/book retorna o livro de um mercado, como a janela «Order book» do site. Três parâmetros obrigatórios definem o mercado: exchange (sem diferenciar maiúsculas), market (spot ou futures) e coin. /orderbooks/coin/{coin} retorna uma lista dos mesmos objetos para todas as exchanges e mercados da moeda.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/book" \
-d exchange=Binance -d market=spot -d coin=BTC \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"exchange": "Binance",
"market": "spot",
"coin": "BTC",
"book_ts": 1794675858,
"age_sec": 6,
"stale": false,
"source": "ws",
"depth_limited": false,
"levels_bid": 500,
"levels_ask": 500,
"best_bid": 96015.9,
"best_ask": 96016,
"bids": [[96015.9, 412300.5], [96015.8, 51020.3], …],
"asks": [[96016, 388120.2], [96016.1, 20410.7], …],
"walls_bid": [[95900, 2410000]],
"walls_ask": [[96500, 1980000]],
"depth_bid_usd": 61234567,
"depth_ask_usd": 58765432
}
| Campo | Significado |
|---|---|
best_bid, best_ask | Melhor bid e melhor ask |
bids, asks | 10 melhores níveis: [preço, valor em USD] |
walls_bid, walls_ask | Maiores paredes: [preço, valor em USD] |
depth_bid_usd, depth_ask_usd | Profundidade de cada lado até ±50% do melhor preço, USD |
book_ts, age_sec, stale | Hora do livro e sua idade em segundos; stale — mais de 30 s |
source, depth_limited | Origem do livro (ws ou rest) e flag de profundidade limitada |
A profundidade de mercado em depth_bid_usd e depth_ask_usd é quantos dólares em ordens há de um lado do livro: no exemplo, cerca de US$ 58,8 milhões em asks de BTC na Binance até +50% do melhor ask.
Com depth_limited: true, a exchange publica um livro parcial e um volume grande pode não ser preenchido. Se não houver livro para essa exchange, mercado e moeda, você recebe 404.
Histórico de execução
/orderbooks/exec-history é o histórico de slippage do Genesis Charts: quanto a execução custava em cada volume da grade, em pontos-base sobre o preço médio do livro (1 pb = 0,01%). Uma requisição aceita até 8 mercados em keys, separados por vírgula; interval é obrigatório.
interval | Passo do ponto | 360 pontos cobrem |
|---|---|---|
1m | 1 minuto | 6 horas |
15m | 15 minutos | 3,75 dias |
1h | 1 hora | 15 dias |
1d | 1 dia | cerca de um ano |
Os dados são coletados desde 6 de setembro de 2026, então a série diária só está preenchida a partir dessa data.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/exec-history" \
--data-urlencode "keys=Binance|spot|BTC,ByBit|futures|BTC" \
-d interval=1h \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"interval": "1h",
"step_sec": 3600,
"points": 360,
"volumes_usd": [500, 1000, 2500, 5000, 10000],
"last_bucket_ts": 1794672000,
"series": {
"Binance|spot|BTC": {
"buy": [[1, 1, 2, …], [1, 2, 2, …], [2, 3, 4, …],
[3, 4, 6, …], [5, 7, 9, …]],
"sell": [[-1, -1, -2, …], …]
},
"ByBit|futures|BTC": { … }
}
}
buy e sell têm cinco séries cada, uma por volume de volumes_usd, com 360 valores do mais antigo ao mais recente. O último ponto pertence a last_bucket_ts, e o ponto i a last_bucket_ts − (points − 1 − i) × step_sec. Os valores de compra são positivos e os de venda negativos: o preço médio da operação fica acima e abaixo do preço médio do livro.
A série [5, 7, 9, …] é uma compra de US$ 10.000: seus primeiros pontos custaram 5–9 pb, ou 0,05–0,09% acima do preço médio. null em uma série significa sem dados ou livro não preenchido; null no lugar de um objeto de mercado significa chave desconhecida.
Slippage em DEX
/orderbooks/dex-slippage descreve a perna DEX de uma operação: slippage de compra e venda de US$ 100 a 100.000, taxas do token e a flag de honeypot por contrato — o mesmo das colunas da tabela DEX do site. Filtros: contract (separados por vírgula para vários) e network.
curl -G "https://api.genesisarbitrage.com/v1/orderbooks/dex-slippage" \
-d contract=0x6982508145454ce325ddbe47a25d4ec3d2311933 \
-H "X-API-Key: gns_live_XXXXXXXXXXXXXXXX"
{
"sizes_usd": [100, 500, 1000, 2500, 5000, 10000, 20000, 50000,
100000],
"contracts": [
{
"contract": "0x6982508145454ce325ddbe47a25d4ec3d2311933",
"network": "ETH",
"tax_buy_pct": 0,
"tax_sell_pct": 0,
"honeypot": "no",
"slippage_buy_pct": [0.31, 0.33, 0.36, 0.44, 0.58, 0.86,
1.41, 3.12, 6.05],
"slippage_sell_pct": [0.31, 0.34, 0.37, 0.46, 0.61, 0.9,
1.5, 3.3, 6.4],
"updated_at": 1794671040
}
]
}
As listas de slippage seguem a grade sizes_usd: no exemplo, uma compra de US$ 5.000 tem slippage de 0,58% e uma de US$ 100.000, de 6,05%. null em uma lista significa que o pool não tem liquidez para esse tamanho.
tax_buy_pct e tax_sell_pct são a taxa de compra e de venda do token, em %; null significa que não há fonte, e não 0%. honeypot: no; suspect — as fontes divergem; yes — a venda pode ser impossível.
Como conferir uma operação com os livros
Pegue uma linha de arbitragem
Encontre uma operação em
/arbitrage/spot-spotou em outro dataset — veja os endpoints de arbitragem. Anote a moeda, as exchanges e ospread_pct.Recalcule o spread pelos livros
Peça
/orderbooks/spreads/spot-spotcom essa moeda e o tamanho da sua operação e comparespread_pctcomorder_delta.spread_pct.Confira a atualidade e a profundidade
Chame
/orderbooks/bookpara as duas pernas:age_sec,staleedepth_limiteddizem se os números são confiáveis, e as paredes mostram onde o preço pode travar.Compare com o histórico
/orderbooks/exec-historymostra se esse slippage é normal para o mercado:1mcobre 6 horas,1hcobre 15 dias.Verifique as taxas da perna DEX
Nas operações DEX – Spot e DEX – Futures, peça
/orderbooks/dex-slippagepara o contrato da linha: slippage, taxas ehoneypot.
Perguntas e respostas
Em que o Δ do order book difere do spread comum?
O spread_pct de uma linha usa os últimos preços das exchanges; o Δ do order book usa os preços médios de operações a mercado no volume dado. A diferença entre os dois é o que o livro leva.
Por que recebo null em vez de um preço?
Em /orderbooks/exec, o livro tem ordens de menos para esse volume; no Δ do order book, o mesmo caso é o status exhausted. No histórico de execução, null significa sem dados no ponto, e no slippage em DEX, que o pool não tem liquidez.
Posso calcular a execução acima de US$ 10.000?
A grade de /orderbooks/exec e do Δ do order book é fixa, de US$ 500 a 10.000. Para tamanhos maiores, veja a profundidade e as paredes em /orderbooks/book; para a perna DEX, /orderbooks/dex-slippage vai até US$ 100.000.