Get Arbitrage Candlestick

📖 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âmetro	Tipo	Obrigatório	Descrição
`ticker`	string	Sim	Par de moedas (ex: “BTC-USDT”, “ETH-USDT”)
`exchanges`	string	Não	Lista de exchanges separadas por vírgula (ex: “binance,coinbase”)
`period`	string	Sim	Perí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íodo	Intervalo	Snapshots/Dia	Total (7 dias)
7 days	5 minutos	288	2,016
15 days	15 minutos	96	1,440
30 days	30 minutos	48	1,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'

API Documentation

Endpoint Examples

📖 Descrição

🛠️ Requisição

Método

URL

Parâmetros de Query

Exemplo de Requisição

Exemplo de Resposta

📝 Notas sobre os Parâmetros

🔍 Exchanges Suportadas

📊 Estrutura de Dados

🎯 ExchangePriceData

💰 ArbitrageOpportunity

📈 ArbitrageStatistics

⚡ Performance e Cache

🚀 Sistema de Cache

📊 Intervalos de Snapshot

🔧 Códigos de Status HTTP

🚨 Tratamento de Erros

📚 Exemplos de Uso

🔍 Análise de BTC-USDT em 7 dias

🎯 Análise específica de exchanges

📊 Análise de longo prazo

​📖 Descrição

​🛠️ Requisição

​Método

​URL

​Parâmetros de Query

​Exemplo de Requisição

​Exemplo de Resposta

​📝 Notas sobre os Parâmetros

​🔍 Exchanges Suportadas

​📊 Estrutura de Dados

​🎯 ExchangePriceData

​💰 ArbitrageOpportunity

​📈 ArbitrageStatistics

​⚡ Performance e Cache

​🚀 Sistema de Cache

​📊 Intervalos de Snapshot

​🔧 Códigos de Status HTTP

​🚨 Tratamento de Erros

​📚 Exemplos de Uso

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

​🎯 Análise específica de exchanges

​📊 Análise de longo prazo

📖 Descrição

🛠️ Requisição

Método

URL

Parâmetros de Query

Exemplo de Requisição

Exemplo de Resposta

📝 Notas sobre os Parâmetros

🔍 Exchanges Suportadas

📊 Estrutura de Dados

🎯 ExchangePriceData

💰 ArbitrageOpportunity

📈 ArbitrageStatistics

⚡ Performance e Cache

🚀 Sistema de Cache

📊 Intervalos de Snapshot

🔧 Códigos de Status HTTP

🚨 Tratamento de Erros

📚 Exemplos de Uso

🔍 Análise de BTC-USDT em 7 dias

🎯 Análise específica de exchanges

📊 Análise de longo prazo