Spread realizável por profundidade

O problema

O spread de uma oportunidade é calculado sobre o topo do livro — o melhor preço de compra contra o melhor preço de venda:

spread = (melhor_bid - melhor_ask) / melhor_ask * 100

Isso responde “qual o spread?” mas não responde “quanto capital cabe nele?”. Um spread de 3% que só existe em 40 USD de liquidez é ruído: na segunda unidade comprada o preço já subiu e o spread evaporou.

O cálculo

O spread realizável consome o livro de ofertas até preencher um alvo de volume e calcula o preço médio ponderado (VWAP) efetivamente pago e recebido:

na exchange de compra, consumimos os asks (é contra eles que se compra);
na exchange de venda, consumimos os bids.

vwapBuy  = notional_preenchido_compra / quantidade_base_compra
vwapSell = notional_preenchido_venda  / quantidade_base_venda

effectiveSpread = (vwapSell - vwapBuy) / vwapBuy * 100

O resultado sai no formato 3.1% @ $1k · 1.9% @ $5k · 0.8% @ $10k: o mesmo par, avaliado em três tamanhos de operação.

O campo `depth`

Oportunidades spot podem trazer um array depth, uma entrada por faixa:

{
  "ticker": "ZEC-USDT",
  "profit_percent_ask_bid": 3.42,
  "depth": [
    {
      "notional": 1000,
      "vwapBuy": 31.61,
      "vwapSell": 32.59,
      "effectiveSpread": 3.10,
      "insufficientLiquidity": false,
      "filledNotionalBuy": 1000,
      "filledNotionalSell": 1000,
      "bookExhaustedBuy": false,
      "bookExhaustedSell": false
    },
    {
      "notional": 10000,
      "vwapBuy": 31.94,
      "vwapSell": 32.19,
      "effectiveSpread": 0.78,
      "insufficientLiquidity": true,
      "filledNotionalBuy": 10000,
      "filledNotionalSell": 2340,
      "bookExhaustedBuy": false,
      "bookExhaustedSell": true
    }
  ]
}

Campo	Significado
`notional`	Alvo da faixa, em USD
`vwapBuy` / `vwapSell`	Preço médio ponderado de cada perna, em USD
`effectiveSpread`	Spread percentual entre os dois VWAP
`insufficientLiquidity`	Pelo menos uma perna não preencheu o alvo
`filledNotionalBuy` / `filledNotionalSell`	Quanto de fato coube em cada perna, em USD
`bookExhaustedBuy` / `bookExhaustedSell`	O book acabou porque a exchange não publicou mais níveis

Quando insufficientLiquidity é true, o effectiveSpread é o spread da liquidez que existia — não do notional pedido. No exemplo acima, os 0.78% referem-se aos

2.340 que couberam, não aos

10.000. É por isso que filledNotional* existe: sem ele, o número parece uma promessa que o livro não sustenta.

Quando `depth` não vem

O campo é opcional e some do payload quando não pôde ser calculado. Todo consumidor precisa tratar a ausência. Os motivos legítimos:

Fora do top-N. A listagem (GET /v1/arbitrage) só enriquece as N oportunidades de maior spread bruto — buscar o book de todas a cada tick multiplicaria o custo de rede. O detalhe (GET /v1/arbitrage/{id}) sempre calcula.
Cotação não suportada. Pares cotados fora de USD/stablecoins, BRL e EUR não têm como ter a faixa convertida.
Book indisponível. Falha ou timeout na consulta à exchange.
Streaming. O canal SSE GET /v1/realtime/arbitrage publica direto do motor de comparação e não passa pelo enriquecimento, então oportunidades vindas por ele nunca trazem depth.
Kill switch. DEPTH_ENABLED=false.

Moedas e conversão

As faixas são definidas em USD para serem comparáveis entre pares. Como o livro está na moeda de cotação, é a faixa que é convertida (alvo = faixa × taxa), não os preços nível a nível — e o VWAP volta para USD no final.

USD, USDT, USDC, BUSD, DAI, TUSD, FDUSD são tratadas como paridade 1:1 com o dólar. Um depeg de 0,3% desloca a faixa de “ $10k" para ~$ 9.970 de profundidade real; como o spread é uma razão, o número de manchete não muda.
BRL e EUR usam a cotação do serviço de câmbio. Ele não atualiza em fins de semana nem fora do horário comercial, então num boot frio de sábado pares nessas moedas podem ficar sem depth.

A taxa se cancela na razão entre os dois VWAP. Uma cotação desatualizada só desloca qual fatia do livro é amostrada — nunca distorce o effectiveSpread.

Profundidade publicada por exchange

O insufficientLiquidity reflete o book que a exchange devolveu. Algumas truncam:

Exchange	Níveis por lado
Binance, Bybit, OKX, Gate.io, Bitget, KuCoin, Kraken, Crypto.com, BingX, HTX, Bitfinex, Mercado Bitcoin	100
Coinbase	~50 (agregado, `level=2`)
MEXC, Bitnuvem	50
Bitstamp, BitMEX	livro completo

Quando o alvo não é atingido por esse limite e não por falta de liquidez real, bookExhausted vem true — a interface mostra “book truncado pela exchange” em vez de “liquidez insuficiente”.

Configuração

Variável	Padrão	Descrição
`DEPTH_BANDS_USD`	`1000,5000,10000`	Faixas em USD, separadas por vírgula. São ordenadas, deduplicadas e limitadas a 8. Uma lista inválida cai no padrão em vez de desligar a feature.
`DEPTH_TOP_N`	`5`	Oportunidades enriquecidas na listagem. `0` desliga só a listagem.
`DEPTH_ENABLED`	`true`	Kill switch global (listagem e detalhe).
`DEPTH_ENRICH_TIMEOUT_MS`	`1500`	Orçamento de latência por request. Faixas que não ficam prontas a tempo são omitidas; o cálculo termina em background e o poll seguinte já encontra o cache quente.

Custo de rede

Cada oportunidade exige dois livros (a perna de compra e a de venda). Três camadas mantêm isso barato:

Corte top-N — de até 25 linhas para 5 na listagem.
Cache de profundidade (20s) — absorve o poll de 10s do front-end, com singleflight colapsando requisições concorrentes idênticas.
Cache de book (4min) — um dado par em uma dada exchange custa no máximo uma ida à rede a cada 4 minutos, independentemente de quantas oportunidades ou clientes o referenciem.

O enriquecimento é sempre não-fatal: qualquer falha resulta na ausência do campo, nunca em erro do request.

​O problema

​O cálculo

​O campo depth

​Quando depth não vem

​Moedas e conversão

​Profundidade publicada por exchange

​Configuração

​Custo de rede

O problema

O cálculo

O campo `depth`

Quando `depth` não vem

Moedas e conversão

Profundidade publicada por exchange

Configuração

Custo de rede