> ## Documentation Index
> Fetch the complete documentation index at: https://docs.arbitragem-crypto.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Entendendo Arbitragem Spot vs Futuros

> Algoritmo de alta precisão para arbitragem entre mercados spot e futuros usando preços bid/ask reais

## 🎯 Algoritmo: Arbitragem Spot vs Futuros (Alta Precisão)

<Callout title="Como funciona?" icon="info-circle" color="blue">
  Este algoritmo de última geração identifica oportunidades de arbitragem entre mercados spot e futuros, usando preços de execução reais (bid/ask) e calculando spreads precisos considerando todos os custos envolvidos.
</Callout>

### 🚀 Características Avançadas:

* ✅ **Precisão Máxima**: Uso de preços bid/ask reais para cálculos precisos
* ✅ **Cobertura Completa**: Avaliação de ambas direções de arbitragem
* ✅ **Threshold Otimizado**: 0.2% para máxima eficiência em HFT
* ✅ **Detecção Inteligente**: Identificação automática de pares equivalentes
* ✅ **Análise em Tempo Real**: Processamento instantâneo de oportunidades

### 1. Identificar o par spot desejado

Exemplo: `LTCBTC`, `ETHBTC`, etc.

### 2. Buscar os preços bid/ask do par no mercado Spot

Chamada na API Spot para o par:

```bash theme={null}
GET /api/v3/ticker/24hr?symbol=LTCBTC
```

Obter:

* `bidPrice` (preço de venda)
* `askPrice` (preço de compra)

<Callout title="💡 Abordagem Avançada" icon="lightbulb" color="yellow">
  O algoritmo utiliza preços bid/ask separados para máxima precisão nos cálculos de arbitragem, garantindo resultados mais confiáveis.
</Callout>

```javascript theme={null}
// ✅ Abordagem de Precisão Máxima
spotBidPrice = bidPrice  // Preço de venda
spotAskPrice = askPrice  // Preço de compra
```

### 3. Identificar os dois pares equivalentes no mercado futuro

<Callout title="Como identificar pares equivalentes?" icon="lightbulb" color="yellow">
  O mercado de futuros normalmente não oferece pares como LTCBTC ou ETHBTC diretamente. Em vez disso, ele oferece contratos contra USDT ou USD.
</Callout>

#### 🔍 **Regra Geral para Conversão:**

Se você tem o par Spot `BASE/QUOTE`:

1. Verifique se `BASE/USDT` e `QUOTE/USDT` existem nos futuros
2. Calcule: `BASE/QUOTE = (BASE/USDT) / (QUOTE/USDT)`

#### 📋 **Exemplos Práticos:**

**Par Spot: LTCBTC**

* Futuros: `LTCUSDT`, `BTCUSDT`
* Resultado: `LTCBTC_futuros = LTCUSDT / BTCUSDT`

**Par Spot: ETHBTC**

* Futuros: `ETHUSDT`, `BTCUSDT`
* Resultado: `ETHBTC_futuros = ETHUSDT / BTCUSDT`

**Par Spot: SOLBTC**

* Futuros: `SOLUSDT`, `BTCUSDT`
* Resultado: `SOLBTC_futuros = SOLUSDT / BTCUSDT`

**Par Spot: DOGEETH**

* Futuros: `DOGEUSDT`, `ETHUSDT`
* Resultado: `DOGEETH_futuros = DOGEUSDT / ETHUSDT`

#### 🧠 **Lógica Matemática Avançada:**

```javascript theme={null}
// Para qualquer par BASE/QUOTE - usando preços bid/ask reais

// Preços Spot
spotBidPrice = BASE/QUOTE_bid
spotAskPrice = BASE/QUOTE_ask

// Preços Futuros Sintéticos
futureBid = (BASE/USDT_bid) / (QUOTE/USDT_ask)  // Para vender
futureAsk = (BASE/USDT_ask) / (QUOTE/USDT_bid)  // Para comprar

// Análise Completa (ambas direções)
spread1 = (futureBid - spotAskPrice) / spotAskPrice  // BUY_SPOT_SELL_FUTURE
spread2 = (spotBidPrice - futureAsk) / futureAsk    // SELL_SPOT_BUY_FUTURE
```

#### 📊 **Tabela de Referência Rápida:**

| Par Spot | Futuro 1 | Futuro 2 | Cálculo Futuro     |
| -------- | -------- | -------- | ------------------ |
| LTCBTC   | LTCUSDT  | BTCUSDT  | LTCUSDT / BTCUSDT  |
| ETHBTC   | ETHUSDT  | BTCUSDT  | ETHUSDT / BTCUSDT  |
| SOLBTC   | SOLUSDT  | BTCUSDT  | SOLUSDT / BTCUSDT  |
| DOGEETH  | DOGEUSDT | ETHUSDT  | DOGEUSDT / ETHUSDT |
| ADAETH   | ADAUSDT  | ETHUSDT  | ADAUSDT / ETHUSDT  |
| LINKBTC  | LINKUSDT | BTCUSDT  | LINKUSDT / BTCUSDT |
| DOTBTC   | DOTUSDT  | BTCUSDT  | DOTUSDT / BTCUSDT  |

<Callout title="Dica Importante" icon="info-circle" color="blue">
  Sempre verifique se ambos os pares futuros existem antes de fazer os cálculos. Alguns pares podem não estar disponíveis em todas as exchanges.
</Callout>

### 4. Buscar os preços bid/ask nos futuros perpétuos

Chamada na API de Futuros:

```bash theme={null}
GET /fapi/v1/ticker/bookTicker?symbol=LTCUSDT
GET /fapi/v1/ticker/bookTicker?symbol=BTCUSDT
```

Obter:

* `bidPrice`, `askPrice` de cada um

<Callout title="💡 Precisão Otimizada" icon="lightbulb" color="yellow">
  O algoritmo mantém preços bid/ask separados para garantir máxima precisão nos cálculos de arbitragem.
</Callout>

```javascript theme={null}
// ✅ Abordagem de Precisão Máxima
// Manter bid/ask separados
ltcBid = bidLTC, ltcAsk = askLTC
btcBid = bidBTC, btcAsk = askBTC
```

### 5. Calcular os preços sintéticos bid/ask do par nos futuros

```javascript theme={null}
// Para VENDER o par sintético (LTC/BTC)
futureBid = ltcBid / btcAsk

// Para COMPRAR o par sintético (LTC/BTC)  
futureAsk = ltcAsk / btcBid
```

### 6. Comparar os preços Spot e Futuros (Análise Completa)

<Callout title="🔄 Análise Bidirecional" icon="lightbulb" color="yellow">
  O algoritmo avalia **ambas direções** de arbitragem simultaneamente para máxima cobertura de oportunidades.
</Callout>

```javascript theme={null}
// OPORTUNIDADE 1: BUY_SPOT_SELL_FUTURE
// Comprar Spot (ask) e Vender Futuros (bid)
spread1 = (futureBid - spotAskPrice) / spotAskPrice

// OPORTUNIDADE 2: SELL_SPOT_BUY_FUTURE  
// Vender Spot (bid) e Comprar Futuros (ask)
spread2 = (spotBidPrice - futureAsk) / futureAsk
```

### 7. Avaliar se há oportunidade de arbitragem

Definir um limiar mínimo de spread para compensar:

* Taxas de negociação
* Slippage
* Funding Rate (no mercado futuro)
* Custo de transferência (se houver)

<Callout title="⚡ Threshold Otimizado" icon="zap" color="blue">
  **Threshold otimizado**: 0.2% para máxima eficiência em trading de alta frequência
</Callout>

```javascript theme={null}
// ✅ Threshold Otimizado para HFT
if (spread1 > 0.2% || spread2 > 0.2%) {
    // Oportunidade identificada
}
```

### 8. Consultar o funding rate atual (se relevante)

Chamada:

```bash theme={null}
GET /fapi/v1/premiumIndex?symbol=LTCUSDT
```

Obter:

* `lastFundingRate`

Avaliar:

* Se estiver positivo, posições long pagam funding
* Se estiver negativo, posições short pagam funding

### 9. Definir estratégia com base na diferença

<Callout title="🎯 Estratégias Inteligentes" icon="lightbulb" color="yellow">
  O algoritmo define estratégias específicas baseadas nos preços de execução reais para máxima precisão.
</Callout>

**OPORTUNIDADE 1: BUY\_SPOT\_SELL\_FUTURE**

* **Condição**: `futureBid > spotAskPrice`
* **Ação**: Comprar no spot (ask) e vender no futuro (bid)
* **Spread**: `(futureBid - spotAskPrice) / spotAskPrice`

**OPORTUNIDADE 2: SELL\_SPOT\_BUY\_FUTURE**

* **Condição**: `spotBidPrice > futureAsk`
* **Ação**: Vender no spot (bid) e comprar no futuro (ask)
* **Spread**: `(spotBidPrice - futureAsk) / futureAsk`

### 10. Executar ordens com gerenciamento de risco

* Verificar saldo disponível
* Verificar limites de posição
* Executar ordens simultaneamente (ou o mais próximo disso)
* Monitorar posições até convergência ou realização do lucro

***

## 📊 Exemplo Prático

<Callout title="Exemplo Real com Algoritmo Avançado" icon="calculator" color="green">
  Vamos simular uma arbitragem com ADABTC usando preços bid/ask reais:
</Callout>

**Dados Spot:**

* Bid: 0.00002000 (preço de venda)
* Ask: 0.00002100 (preço de compra)

**Dados Futuros:**

* ADAUSDT Bid: 0.9, Ask: 0.95
* BTCUSDT Bid: 50000, Ask: 50010

**Cálculo dos Preços Sintéticos:**

* Future Bid = 0.9 / 50010 = 0.00001800 (para vender ADA/BTC)
* Future Ask = 0.95 / 50000 = 0.00001900 (para comprar ADA/BTC)

**Avaliação das Oportunidades:**

**OPORTUNIDADE 1: BUY\_SPOT\_SELL\_FUTURE**

* Spread = (0.00001800 - 0.00002100) / 0.00002100 = -14.29% ❌

**OPORTUNIDADE 2: SELL\_SPOT\_BUY\_FUTURE**

* Spread = (0.00002000 - 0.00001900) / 0.00001900 = 5.26% ✅

**Resultado:** Oportunidade encontrada! Spread de 5.26% > threshold de 0.2%

***

## ⚠️ Considerações Importantes

<Callout title="Riscos" icon="alert-triangle" color="red">
  A arbitragem spot vs futuros envolve riscos significativos:
</Callout>

1. **Funding Rate**: Pode eliminar lucros se não for considerado
2. **Liquidez**: Ordens grandes podem causar slippage
3. **Tempo de execução**: Diferenças de timing podem afetar resultados
4. **Correlação**: Mercados spot e futuros podem se mover juntos
5. **Regulamentação**: Diferentes regras podem aplicar em cada mercado

***

## 📈 Contagem de cruzamentos (Spot x Future)

A API expõe endpoints para **processar** e **consultar** a quantidade de cruzamentos de preço (spot x future) por ticker e exchange:

* **POST** `/v1/arbitrage/future/crossing-counts`: dispara o processamento assíncrono do dia (consulta operações spot x future, agrupa por ticker e exchange, conta cruzamentos e persiste na coleção `spot_future_crossing_counts` de forma idempotente — *upsert* por `(processing_date, ticker, exchange)`). Retorna `202 Accepted`.
* **GET** `/v1/arbitrage/future/crossing-count?ticker=...&exchange=...`: retorna o `crossingCount` somado sobre os **últimos 7 dias** para aquele par, com filtro `crossing_count > 0`. O resultado é cacheado por 4 horas. A resposta inclui o campo **`spotXFuture: true`**, indicando que o dado se refere ao contexto Spot x Future. Se não houver registro na janela, retorna `crossingCount: 0`.

Documentação detalhada: [Process Crossing Counts](/api-reference/endpoint/process-crossing-counts) e [Get Crossing Count](/api-reference/endpoint/get-crossing-count).

***

## 🔧 Implementação Técnica

```python theme={null}
def calculate_spot_future_arbitrage(symbol):
    # 1. Buscar dados spot (bid/ask separados)
    spot_data = get_spot_ticker(symbol)
    spot_bid = spot_data['bidPrice']  # Preço de venda
    spot_ask = spot_data['askPrice']  # Preço de compra
    
    # 2. Decompor símbolo
    base, quote = decompose_symbol(symbol)
    
    # 3. Buscar dados futuros (bid/ask separados)
    base_future = get_future_ticker(f"{base}USDT")
    quote_future = get_future_ticker(f"{quote}USDT")
    
    # 4. Calcular preços sintéticos bid/ask
    future_bid = base_future['bidPrice'] / quote_future['askPrice']  # Para vender
    future_ask = base_future['askPrice'] / quote_future['bidPrice']  # Para comprar
    
    # 5. Avaliar ambas direções de arbitragem
    opportunities = []
    
    # OPORTUNIDADE 1: BUY_SPOT_SELL_FUTURE
    spread1 = (future_bid - spot_ask) / spot_ask
    if spread1 > 0.002:  # 0.2% threshold
        opportunities.append({
            'strategy': 'BUY_SPOT_SELL_FUTURE',
            'spot_price': spot_ask,
            'future_price': future_bid,
            'spread': spread1,
            'profitable': True
        })
    
    # OPORTUNIDADE 2: SELL_SPOT_BUY_FUTURE
    spread2 = (spot_bid - future_ask) / future_ask
    if spread2 > 0.002:  # 0.2% threshold
        opportunities.append({
            'strategy': 'SELL_SPOT_BUY_FUTURE',
            'spot_price': spot_bid,
            'future_price': future_ask,
            'spread': spread2,
            'profitable': True
        })
    
    return {
        'symbol': symbol,
        'opportunities': opportunities,
        'total_opportunities': len(opportunities)
    }
```

***

## 🧪 Testes e Validação

<Callout title="✅ Validação Completa" icon="check-circle" color="green">
  O algoritmo inclui testes unitários abrangentes para garantir máxima confiabilidade:
</Callout>

### Casos de Teste Cobertos:

* ✅ **TestCompareSpotXFuture**: Valida o algoritmo principal
* ✅ **TestIdentifyEquivalentPairsInFuture**: Testa identificação de pares
* ✅ **TestCalculateSyntheticFuturePrices**: Verifica cálculo de preços sintéticos

### Resultado dos Testes:

```
=== RESULTADOS DO TESTE DE ARBITRAGEM SPOT X FUTUROS ===
Número de oportunidades encontradas: 1

--- OPORTUNIDADE 1 ---
Symbol: ADA/BTC
SpotPrice (preço de execução): 0.00002000
FuturePrice (preço de execução): 0.00001900
Spread absoluto: 0.00000100
Spread percentual: 5.26%
Estratégia: SELL_SPOT_BUY_FUTURE
Funding Rate: 0.0001 (0.01%)
É lucrativa: true

✅ TESTE CONCLUÍDO COM SUCESSO
```

***

<Callout title="Próximos Passos" icon="rocket" color="purple">
  Para implementar este algoritmo avançado em produção, considere:

  * ✅ **Algoritmo Validado**: Testes unitários passando
  * 🔄 **Backtesting**: Com dados históricos usando preços bid/ask reais
  * 🔄 **Monitoramento**: De funding rates em tempo real
  * 🔄 **Otimização**: De execução de ordens simultâneas
  * 🔄 **Expansão**: Para outras exchanges seguindo o padrão otimizado
</Callout>