Skip to main content

​
📖 Descrição

Este endpoint retorna dados históricos de arbitragem em formato de candlestick, baseados nos dados armazenados na collection operations_audit do MongoDB. Os dados são agregados em snapshots temporais com oportunidades de arbitragem calculadas.
Esta funcionalidade utiliza dados históricos já processados, não fazendo chamadas em tempo real para APIs externas, garantindo performance e consistência.

​
🛠️ Requisição

​
Método

GET

​
URL

/v1/candlestick

​
Parâmetros de Query

ParâmetroTipoObrigatórioDescrição
tickerstringSimPar de moedas (ex: “BTC-USDT”, “ETH-USDT”)
exchangesstringNãoLista de exchanges separadas por vírgula (ex: “binance,coinbase”)
periodstringSimPeríodo de análise: “7 days”, “15 days”, “30 days”

​
Exemplo de Requisição

curl --location 'localhost:8080/v1/candlestick?ticker=BTC-USDT&exchanges=binance,coinbase,kraken&period=7%20days'

​
Exemplo de Resposta

{
  "ticker": "BTC-USDT",
  "exchanges": ["binance", "coinbase", "kraken"],
  "period": "7 days",
  "start_time": "2024-01-01T00:00:00Z",
  "end_time": "2024-01-08T00:00:00Z",
  "data": [
    {
      "timestamp": "2024-01-01T10:00:00Z",
      "exchange_data": {
        "binance": {
          "exchange_name": "binance",
          "symbol": "BTC-USDT",
          "bid_price": 45000.0,
          "ask_price": 45050.0,
          "bid_qty": 1.5,
          "ask_qty": 2.0,
          "bid_volume": 67500.0,
          "ask_volume": 90100.0,
          "total_volume": 157600.0,
          "last_price": 45025.0,
          "spread": 50.0,
          "spread_percentage": 0.11
        },
        "coinbase": {
          "exchange_name": "coinbase",
          "symbol": "BTC-USDT",
          "bid_price": 44980.0,
          "ask_price": 45030.0,
          "bid_qty": 1.2,
          "ask_qty": 1.8,
          "bid_volume": 53976.0,
          "ask_volume": 81054.0,
          "total_volume": 135030.0,
          "last_price": 45005.0,
          "spread": 50.0,
          "spread_percentage": 0.11
        }
      },
      "arbitrage_opportunities": [
        {
          "buy_exchange": "coinbase",
          "sell_exchange": "binance",
          "buy_price": 45030.0,
          "sell_price": 45000.0,
          "buy_qty": 1.2,
          "sell_qty": 1.2,
          "spread": -30.0,
          "spread_percentage": -0.07,
          "buy_fee": 54.04,
          "sell_fee": 54.0,
          "withdraw_fee": 0.0,
          "net_profit": -138.04,
          "net_profit_percentage": -0.31,
          "min_trade_amount": 450.3,
          "max_trade_amount": 54036.0,
          "is_profitable": false,
          "liquidity_score": 135030.0
        }
      ]
    }
  ],
  "statistics": {
    "total_snapshots": 168,
    "total_opportunities": 5040,
    "profitable_count": 1200,
    "avg_spread_percentage": 0.15,
    "max_spread_percentage": 2.5,
    "min_spread_percentage": -1.2,
    "avg_net_profit_percentage": 0.08,
    "max_net_profit_percentage": 1.8,
    "best_exchange_pair": "binance-coinbase",
    "total_volume": 125000.5
  }
}

​
📝 Notas sobre os Parâmetros

Parâmetros de Query:
  • ticker: Deve ser exatamente igual ao formato armazenado no banco (ex: “BTC-USDT”)
  • exchanges: Se não especificado, usa todas as exchanges disponíveis
  • period: Define o intervalo de snapshot (5min para 7 dias, 15min para 15 dias, 30min para 30 dias)

​
🔍 Exchanges Suportadas

As exchanges suportadas são as mesmas disponíveis no sistema principal:
  • binance, coinbase, kraken, kucoin, gateio
  • okx, bybit, mexc, htx, bitfinex
  • bitstamp, bitget, novadax, bingx
  • bitnuvem, crypto-ponto-com, mercado-btc
Certifique-se de que as exchanges especificadas estejam entre as suportadas pelo sistema.

​
📊 Estrutura de Dados

​
🎯 ExchangePriceData

{
  exchange_name: string,        // Nome da exchange
  symbol: string,              // Par de moedas
  bid_price: number,           // Preço de compra
  ask_price: number,           // Preço de venda
  bid_qty: number,             // Quantidade disponível para compra
  ask_qty: number,             // Quantidade disponível para venda
  bid_volume: number,          // Volume de compra
  ask_volume: number,          // Volume de venda
  total_volume: number,        // Volume total
  last_price: number,          // Preço médio
  spread: number,              // Spread absoluto
  spread_percentage: number    // Spread percentual
}

​
💰 ArbitrageOpportunity

{
  buy_exchange: string,           // Exchange de compra
  sell_exchange: string,          // Exchange de venda
  buy_price: number,              // Preço de compra
  sell_price: number,             // Preço de venda
  buy_qty: number,                // Quantidade para compra
  sell_qty: number,               // Quantidade para venda
  spread: number,                 // Spread absoluto
  spread_percentage: number,      // Spread percentual
  buy_fee: number,                // Taxa de compra
  sell_fee: number,               // Taxa de venda
  withdraw_fee: number,           // Taxa de saque
  net_profit: number,             // Lucro líquido
  net_profit_percentage: number,  // Lucro percentual
  min_trade_amount: number,       // Valor mínimo de trade
  max_trade_amount: number,       // Valor máximo de trade
  is_profitable: boolean,         // Se é lucrativo
  liquidity_score: number         // Score de liquidez
}

​
📈 ArbitrageStatistics

{
  total_snapshots: number,        // Total de snapshots
  total_opportunities: number,    // Total de oportunidades
  profitable_count: number,       // Oportunidades lucrativas
  avg_spread_percentage: number,  // Spread médio
  max_spread_percentage: number,  // Spread máximo
  min_spread_percentage: number,  // Spread mínimo
  avg_net_profit_percentage: number,  // Lucro médio
  max_net_profit_percentage: number,  // Lucro máximo
  best_exchange_pair: string,     // Melhor par de exchanges
  total_volume: number            // Volume total
}

​
⚡ Performance e Cache

​
🚀 Sistema de Cache

  • Duração: 2 horas por chave
  • Chave: arbitrage_candlestick:{ticker}:{exchanges}:{period}
  • Backend: Redis (se configurado) ou memória local

​
📊 Intervalos de Snapshot

PeríodoIntervaloSnapshots/DiaTotal (7 dias)
7 days5 minutos2882,016
15 days15 minutos961,440
30 days30 minutos481,440

​
🔧 Códigos de Status HTTP

  • 200 OK: Sucesso
  • 400 Bad Request: Parâmetros inválidos ou ausentes
  • 500 Internal Server Error: Erro interno do servidor

​
🚨 Tratamento de Erros

{
  "error": "Missing required parameters: ticker, period"
}

{
  "error": "Invalid period. Use: 7 days, 15 days, or 30 days"
}

​
📚 Exemplos de Uso

​
🔍 Análise de BTC-USDT em 7 dias

curl 'localhost:8080/v1/candlestick?ticker=BTC-USDT&period=7%20days'

​
🎯 Análise específica de exchanges

curl 'localhost:8080/v1/candlestick?ticker=ETH-USDT&exchanges=binance,coinbase,kraken&period=15%20days'

​
📊 Análise de longo prazo

curl 'localhost:8080/v1/candlestick?ticker=ADA-USDT&period=30%20days'
Dica: Use ferramentas como jq para processar as respostas JSON e extrair métricas específicas:
curl 'localhost:8080/v1/candlestick?ticker=BTC-USDT&period=7%20days' | jq '.statistics.best_exchange_pair'