Genesis Arbitrage

Genesis Arbitrage · · 15 min de leitura

API de livro de ofertas cripto: profundidade, preço de execução e slippage entre exchanges

Em resumo

  • Uma API de livro de ofertas retorna os níveis de compra e de venda — o preço e o tamanho de cada um — como um snapshot REST ou um stream WebSocket de mudanças. O melhor bid e o melhor ask descrevem apenas os primeiros dólares de uma negociação.
  • A profundidade define o preço de uma ordem grande. Em um exemplo hipotético, uma compra de US$ 10.000 percorre cinco níveis, seu preço médio fica 25 pontos-base acima do ponto médio do livro e o spread entre exchanges cai de 1,20% para 0,70%.
  • Nos planos Pro e Max, a Genesis API retorna preços de execução prontos para US$ 500–10.000, o Δ do order book para as linhas de arbitragem, a idade e a profundidade dos livros, o histórico de slippage e uma escada de slippage em DEX. Apenas REST; os livros ficam de 5 a 20 segundos atrás da exchange.

Uma API de livro de ofertas cripto retorna as ordens de compra e de venda atuais de um par, agrupadas por nível de preço: cada nível traz um preço e o tamanho que está nele. A partir desses níveis calculam-se o preço de execução de uma ordem de determinado tamanho, o slippage e a profundidade de mercado e, com os livros de duas exchanges, quanto do spread sobrevive a uma negociação real.

Uma exchange serve o próprio livro como snapshot REST ou stream WebSocket, enquanto a Genesis API, nos planos Pro e Max, serve preços de execução, profundidade e Δ do order book já calculados para várias exchanges ao mesmo tempo.

O que uma API de livro de ofertas retorna

Um livro de ofertas é a lista de ordens limitadas abertas de um par. As ordens de compra (bids) são ordenadas do preço mais alto para baixo, as de venda (asks) do mais baixo para cima. Um nível é um preço e o tamanho total nele; a distância entre o melhor ask e o melhor bid é o spread do livro.

Um snapshot REST é a resposta a uma única requisição: os níveis naquele momento. O endpoint do livro de ofertas da Binance é público e não exige chave de API; aqui está uma requisição dos cinco melhores níveis de BTC/USDT e uma resposta (os números são hipotéticos):

curl "https://api.binance.com/api/v3/depth?symbol=BTCUSDT&limit=5"
{
  "lastUpdateId": 81273645120,
  "bids": [["96015.90000000", "1.25000000"], …],
  "asks": [["96016.00000000", "0.84100000"], …]
}

Cada nível chega como um par de strings [preço, quantidade], com a quantidade em moedas: o melhor bid contém 1,25 × 96.015,9 = US$ 120.019,88. O parâmetro limit é 100 por padrão e vai até 5.000 níveis por lado (documentação da Binance).

Um stream WebSocket é enviado pela exchange por uma conexão persistente. A Binance tem dois tipos de streams de livro: btcusdt@depth5, btcusdt@depth10 e btcusdt@depth20 enviam os 5, 10 ou 20 melhores níveis, enquanto btcusdt@depth envia apenas as mudanças. Ambos atualizam a cada 1000 ms, ou a cada 100 ms com o sufixo @100ms (streams WebSocket da Binance).

Um livro local completo é montado a partir de um snapshot mais o stream de diferenças, comparando o lastUpdateId do snapshot com os IDs de atualização dos eventos; se um evento for perdido, o livro é reconstruído do zero.

MétodoO que você recebePara que usar
Snapshot RESTNíveis no momento da requisição, até 5.000 por lado na BinanceVerificações pontuais, consultas pouco frequentes
Stream WebSocketMelhores níveis ou mudanças a cada 100–1000 msUm livro local em memória, um bot de trading
Genesis API via RESTNíveis como [price, valor em USD], preço de execução, profundidade e idade do livroComparar exchanges, conferir uma operação

Por que o melhor bid e ask enganam em volume

O melhor ask é o preço apenas do primeiro nível. Uma compra a mercado maior que esse nível toma os seguintes, mais caros, e o preço médio de execução sobe — isso é o slippage.

Um exemplo hipotético: o token ABC na exchange A, melhor bid 0,9996, melhor ask 1,0004, ponto médio do livro 1,0000. Uma compra a mercado de US$ 10.000 percorre cinco níveis de ask:

Preço do askNo livro, US$Tomado, US$Moedas
1,00041.1001.1001.099,56
1,00101.4001.4001.398,60
1,00182.6002.6002.595,33
1,00303.0003.0002.991,03
1,00506.0001.9001.890,55

A ordem compra 9.975,07 moedas no total. O preço médio de execução é o VWAP, o preço médio ponderado pelo volume: 10.000 / 9.975,07 ≈ 1,0025.

Slippage em relação ao melhor ask: (1,0025 − 1,0004) / 1,0004 × 100 ≈ 0,21%. Em relação ao ponto médio do livro: (1,0025 − 1,0000) / 1,0000 × 10.000 = 25 pontos-base. Quatro deles são metade do spread do livro, que toda compra a mercado paga; os outros 21 vêm da profundidade.

Profundidade de mercado dentro de ±X% e paredes

A profundidade de mercado é o tamanho total das ordens dentro de uma distância dada do melhor preço. No exemplo, os asks dentro de +0,2% do melhor, até 1,0024, somam 1.100 + 1.400 + 2.600 = US$ 5.100, e dentro de +0,5%, até 1,0054, US$ 14.100.

Leia a profundidade como capacidade: uma ordem maior que a profundidade dentro de +0,2% será executada em níveis além desse limite. Na exchange A, uma compra de US$ 5.000 cabe nele, e uma de US$ 10.000 não.

Uma parede é uma ordem grande em um único nível, visivelmente maior que as vizinhas: US$ 6.000 em 1,0050 no exemplo. Enquanto a parede se mantém, ela segura o preço, mas pode ser retirada um segundo antes de a sua ordem chegar a ela, e a compra é então executada nos níveis atrás dela.

Na Genesis API a profundidade vem de /orderbooks/book, o livro de um mercado, e de /orderbooks/coin/{coin}, os livros de uma moeda em todas as exchanges e mercados ao mesmo tempo (Order book do mercado, Order books da moeda). A resposta traz os 10 melhores bids e asks como [price, valor em USD], as maiores paredes em walls_bid e walls_ask, e a profundidade de todo o lado dentro de ±50% do melhor preço em depth_bid_usd e depth_ask_usd. Um corredor de ±50% é largo; para um tamanho específico, olhe os níveis ou o preço de execução já calculado.

Idade do livro: livros desatualizados e profundidade limitada

Todo snapshot de livro tem uma idade. Se o livro de uma exchange é 15 segundos mais antigo que o da outra, parte do spread entre elas pode ser uma defasagem de tempo: o preço no livro mais antigo já mudou.

Na Genesis API os livros ficam de 5 a 20 segundos atrás da exchange, e cada um traz sua idade. O início de uma resposta de /orderbooks/book da documentação:

{
  "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,
  …
}

book_ts é a hora do livro em segundos unix, age_sec a sua idade em segundos, e stale: true marca um livro com mais de 30 segundos. source mostra como o livro foi obtido da exchange: por WebSocket (ws) ou por requisições REST (rest).

depth_limited: true significa que a exchange publica profundidade limitada: os totais são parciais e uma ordem grande pode não ser executada. Quando as ordens acabam, /orderbooks/exec retorna null em vez de um preço, e o Δ do order book retorna o status exhausted.

Spread executável entre exchanges: Δ do order book

De volta ao exemplo hipotético. Na exchange B a última negociação saiu a 1,0120, o melhor bid é 1,0116 e o ask 1,0124. Os bids de B têm US$ 1.100 em 1,0116, US$ 1.300 em 1,0110, US$ 2.800 em 1,0102, US$ 2.900 em 1,0090 e US$ 5.000 em 1,0070.

Vender US$ 10.000 nesses bids dá um VWAP de 1,0095 pela mesma fórmula. Isso é (1,0120 − 1,0095) / 1,0120 × 10.000 ≈ 24,7 pontos-base abaixo do ponto médio do livro de B.

Como o spread é calculadoComprar em A → vender em BSpread
Últimas negociações, como em uma linha da tabela1,0000 → 1,01201,20%
Melhores preços do livro1,0004 → 1,01161,12%
Após executar US$ 10.0001,0025 → 1,00950,70%

Spread da linha: (1,0120 − 1,0000) / 1,0000 × 100 = 1,20%. Após a execução: (1,0095 − 1,0025) / 1,0025 × 100 ≈ 0,70%. A linha promete US$ 120 sobre US$ 10.000, e restam cerca de US$ 70 depois dos livros: 10.000 × 0,006983 ≈ 69,83.

Dos 50 pontos-base perdidos, 8 foram para a distância entre a última negociação e as melhores ordens, e os outros 42 para a profundidade dos dois livros.

O Δ do order book é como a Genesis Arbitrage chama o spread de uma linha recalculado pelos livros de ofertas para um tamanho dado; no site é a coluna «Δ por ordens» das tabelas de arbitragem, por exemplo Spot – Futuros. Na API ele vem de /orderbooks/spreads/{dataset}: cada linha de uma moeda no dataset spot-spot, spot-futures, futures-futures, dex-spot ou dex-futures recebe um objeto order_delta (Δ do order book).

order_delta traz buy_price e sell_price para o tamanho escolhido, o spread_pct após a execução e um status: ok, no_book (sem livro) ou exhausted (o livro não foi preenchido). O volume é 0 (melhores preços do livro) ou 500, 1000, 2500, 5000, 10000, e o resultado nunca excede o spread da linha. As linhas de DEX trazem side e cex_price em vez de um par de preços: o lado CEX e o seu preço de execução.

Os próprios preços de execução, para todos os mercados de uma vez, vêm de /orderbooks/exec: um par [preço de compra, preço de venda] sob uma chave como Binance|spot|BTC, com null onde o livro é raso demais (Preços de execução).

A operação completa, com a transferência da moeda e as verificações de rede, está em Arbitragem de criptomoedas entre exchanges.

Exemplo em Python: spread da linha vs spread após a execução

O script pega operações Spot – Spot com spread de pelo menos 0,5%, solicita o Δ do order book a US$ 5.000 para as dez moedas com os maiores spreads e imprime quantos pontos-base os livros consumiram. A chave vem da variável de ambiente GENESIS_API_KEY. Em 429 e 503 o script espera Retry-After segundos e, se a espera for maior que um minuto — a cota mensal acabou —, ele para.

import os
import time
import requests

BASE = "https://api.genesisarbitrage.com/v1"
HEADERS = {"X-API-Key": os.environ["GENESIS_API_KEY"]}
VOLUME = 5000      # dólares por perna
MIN_SPREAD = 0.5   # spread da linha, %


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):
            wait = int(r.headers.get("Retry-After", "5"))
            if wait > 60:  # a cota mensal acabou
                break
            time.sleep(wait)
            continue
        r.raise_for_status()
        return r.json()["data"]
    raise RuntimeError("A API não respondeu, tente novamente mais tarde")


rows = get("/arbitrage/spot-spot", {"min_spread": MIN_SPREAD})
rows.sort(key=lambda x: x["spread_pct"], reverse=True)
coins = list(dict.fromkeys(x["coin"] for x in rows))[:10]

for coin in coins:
    data = get("/orderbooks/spreads/spot-spot",
               {"coin": coin, "volume": VOLUME})
    for row in data:
        od = row["order_delta"]
        if row["spread_pct"] < MIN_SPREAD or od["status"] != "ok":
            continue  # no_book ou exhausted: o tamanho não será executado
        lost = (row["spread_pct"] - od["spread_pct"]) * 100
        print(f'{coin} {row["exchange_buy"]}→{row["exchange_sell"]}'
              f' {row["spread_pct"]:.2f}% → {od["spread_pct"]:.2f}%,'
              f' os livros consumiram {lost:.0f} pb')
    time.sleep(0.25)  # até 4 requisições por segundo: o Pro permite 5

O script faz até 11 chamadas com pausa de 0,25 s entre as moedas. Execute-o em loop com frequência não maior que meta.freshness_sec: 10 s no Pro e 5 s no Max (limites da Genesis API). Para adicionar notificações, veja Bot de arbitragem de criptomoedas em Python.

Histórico do custo de execução

Um único snapshot não diz se o slippage atual é normal para o mercado ou se o livro está mais raso que o habitual. /orderbooks/exec-history retorna o histórico da Genesis Charts: quantos pontos-base em relação ao ponto médio do livro custa uma execução de US$ 500, 1.000, 2.500, 5.000 e 10.000, separadamente para compras e vendas (Histórico de execução).

Cada intervalo tem 360 pontos: 1m cobre 6 horas, 15m 3,75 dias, 1h 15 dias e 1d cerca de um ano, com dados desde 6 de setembro de 2026. Uma requisição aceita até 8 mercados no parâmetro keys. Os valores de compra são positivos e os de venda negativos; null significa que não há dados ou que o livro não foi preenchido. A Genesis API não serve snapshots passados do próprio livro.

import os
import statistics
import requests

KEY = "Binance|spot|BTC"
r = requests.get(
    "https://api.genesisarbitrage.com/v1/orderbooks/exec-history",
    headers={"X-API-Key": os.environ["GENESIS_API_KEY"]},
    params={"keys": KEY, "interval": "1h"},  # 360 horas, 15 dias
    timeout=15,
)
r.raise_for_status()
data = r.json()["data"]
series = data["series"][KEY]
if series is None:
    raise SystemExit("mercado não encontrado: " + KEY)
i = data["volumes_usd"].index(10000)  # a série de compra de US$ 10.000
buy = series["buy"][i]
known = [x for x in buy if x is not None]
if not known:
    raise SystemExit("sem dados para o período")
print("mediana de 15 dias, pb:", statistics.median(known))
print("último ponto, pb:", buy[-1])

Hipoteticamente, se a mediana de 15 dias é de 12 pontos-base e o último ponto é 25, executar agora custa o dobro do habitual, e faz sentido aumentar o limite de spread para essa moeda.

DEX: escada de slippage, taxas de tokens e honeypots

Um pool de DEX não tem livro de ofertas: o preço do swap vem da fórmula do pool, e quanto maior a negociação em relação à liquidez, mais o preço se move. Por isso uma perna de DEX é avaliada com uma escada: o slippage em uma série de tamanhos.

/orderbooks/dex-slippage retorna, por contrato, o slippage de compra e de venda em US$ 100, 500, 1.000, 2.500, 5.000, 10.000, 20.000, 50.000 e 100.000, as taxas do token e o flag de honeypot, o mesmo das colunas da tabela DEX do site (Slippage em DEX). Na resposta de exemplo da documentação, o slippage de compra é 0,86% em US$ 10.000, 3,12% em US$ 50.000 e 6,05% em US$ 100.000.

Isso define o limite de uma operação: um spread DEX – CEX de 2% sobrevive ao slippage do pool em US$ 10.000, mas não em US$ 50.000, mesmo antes das taxas. null na escada significa que o pool não tem liquidez para esse tamanho, e o gas da rede não está na resposta, então conte-o à parte.

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 deve ser lido como zero. honeypot: no — sem sinais, suspect — as fontes divergem, yes — vender o token pode ser impossível.

Para verificar um token manualmente, veja Como verificar um token antes de comprar; para preços e liquidez de DEX ao lado de CEX, veja API de DEX.

Livros de ofertas na Genesis API: endpoints e planos

TarefaEndpoint
Preço de execução para US$ 500–10.000 em todos os mercados/orderbooks/exec
O spread de uma linha após a execução/orderbooks/spreads/{dataset}
10 níveis, paredes, profundidade e idade do livro/orderbooks/book
Os livros de uma moeda em todas as exchanges/orderbooks/coin/{coin}
Histórico do custo de execução/orderbooks/exec-history
Slippage em DEX, taxas e o flag honeypot/orderbooks/dex-slippage

Os seis fazem parte dos planos de API Pro e Max. O Pro custa US$ 100 por mês: 5 M de chamadas, 5 requisições por segundo, atualidade de 10 s. O Max custa US$ 200: 10 M de chamadas, 15 requisições por segundo, 5 s; no Trial e no Start os endpoints de livros de ofertas retornam 403 plan_restricted.

Parâmetros e exemplos de resposta estão no guia de endpoints de livros de ofertas; para uma visão geral dos dados da API, veja API de criptomoedas e a lição Dados de API para arbitragem.

Perguntas e respostas

Por que o spread da tabela é maior do que o que consigo na negociação?

O spread da linha vem das últimas negociações, enquanto uma ordem a mercado é executada contra o livro, e quanto maior o tamanho, mais o preço médio se afasta do melhor. As taxas e o movimento do preço durante a transferência vêm por cima. O Δ do order book mostra quanto do spread sobra no seu tamanho.

Com que frequência os livros de ofertas são atualizados?

Um livro muda a cada nova ordem e a cada cancelamento; o stream da Binance envia mudanças a cada 100 ou 1000 ms. Na Genesis API os livros ficam de 5 a 20 segundos atrás da exchange (a idade está em age_sec), e as respostas são atualizadas a cada 10 segundos no Pro e a cada 5 segundos no Max.

A Genesis API tem WebSocket para livros de ofertas?

Não. A Genesis API é apenas REST: uma requisição HTTP GET e uma resposta JSON. Os streams de livros em tempo real vêm dos WebSockets das próprias exchanges, e é isso que um bot que coloca ordens pela API de trading de uma exchange precisa.

Existe uma API de livro de ofertas gratuita?

As exchanges têm endpoints públicos: o livro da Binance em /api/v3/depth responde sem chave, mas cobre uma única exchange e o preço de execução você calcula por conta própria. A Genesis API não tem plano gratuito; os livros de ofertas estão incluídos no Pro, a US$ 100 por mês, e no Max, a US$ 200.