Genesis Arbitrage

Genesis Arbitrage · · 12 min de leitura

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; null significa que o livro é raso demais para esse volume.
  • Os livros atrasam de 5 a 20 segundos em relação à exchange: confira age_sec e stale, 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

EndpointO que retornaObrigatórioDocumentação
/orderbooks/execPreços de compra e venda para um volume em cada mercadovolumePreços de execução
/orderbooks/spreads/{dataset}Δ do order book para as linhas de uma moeda em um dataset de arbitragemcoinΔ do order book
/orderbooks/bookLivro de um mercado: 10 níveis, paredes, profundidade, idadeexchange, market, coinOrder book do mercado
/orderbooks/coin/{coin}Livros de uma moeda em todas as exchanges e mercadosmoeda no caminhoOrder books da moeda
/orderbooks/exec-historyHistórico de slippage, até 8 mercados por requisiçãokeys, intervalHistórico de execução
/orderbooks/dex-slippageSlippage, 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âmetroTipoO que faz
volumenúmeroVolume em USD: 500, 1000, 2500, 5000 ou 10000, obrigatório
exchangestringFiltra por exchange; separadas por vírgula para várias
marketstringspot ou futures
coinstringTicker 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âmetroTipoO que faz
{dataset}string, no caminhospot-spot, spot-futures, futures-futures, dex-spot ou dex-futures
coinstringTicker da moeda, obrigatório
volumenúmero0 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
}
CampoSignificado
best_bid, best_askMelhor bid e melhor ask
bids, asks10 melhores níveis: [preço, valor em USD]
walls_bid, walls_askMaiores paredes: [preço, valor em USD]
depth_bid_usd, depth_ask_usdProfundidade de cada lado até ±50% do melhor preço, USD
book_ts, age_sec, staleHora do livro e sua idade em segundos; stale — mais de 30 s
source, depth_limitedOrigem 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.

intervalPasso do ponto360 pontos cobrem
1m1 minuto6 horas
15m15 minutos3,75 dias
1h1 hora15 dias
1d1 diacerca 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

  1. Pegue uma linha de arbitragem

    Encontre uma operação em /arbitrage/spot-spot ou em outro dataset — veja os endpoints de arbitragem. Anote a moeda, as exchanges e o spread_pct.

  2. Recalcule o spread pelos livros

    Peça /orderbooks/spreads/spot-spot com essa moeda e o tamanho da sua operação e compare spread_pct com order_delta.spread_pct.

  3. Confira a atualidade e a profundidade

    Chame /orderbooks/book para as duas pernas: age_sec, stale e depth_limited dizem se os números são confiáveis, e as paredes mostram onde o preço pode travar.

  4. Compare com o histórico

    /orderbooks/exec-history mostra se esse slippage é normal para o mercado: 1m cobre 6 horas, 1h cobre 15 dias.

  5. Verifique as taxas da perna DEX

    Nas operações DEX – Spot e DEX – Futures, peça /orderbooks/dex-slippage para o contrato da linha: slippage, taxas e honeypot.

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.