> ## 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.

# Candlestick de Arbitragem

## 📊 Visão Geral

A funcionalidade de **Candlestick de Arbitragem** permite gerar dados históricos de arbitragem em formato de candlestick, baseados nos dados já processados e armazenados na collection `operations_audit` do MongoDB.

<Callout title="Dados Históricos" icon="database" color="blue">
  Esta feature utiliza dados históricos já processados, não fazendo chamadas em tempo real para APIs externas, garantindo performance e consistência.
</Callout>

***

## 🎯 Funcionalidades

### ✅ **Características Principais**

* **📈 Dados Históricos**: Utiliza dados da collection `operations_audit`
* **⏱️ Agregação Temporal**: Snapshots em intervalos de 5min, 15min, 30min
* **🔄 Cache Inteligente**: Cache de 2 horas para otimização
* **📊 Estatísticas Consolidadas**: Métricas de performance de arbitragem
* **🎯 Filtros Precisos**: Por ticker, exchanges e período

### 📊 **Intervalos por Período**

| Período | Intervalo de Snapshot | Descrição                     |
| ------- | --------------------- | ----------------------------- |
| 7 days  | 5 minutos             | Dados detalhados para análise |
| 15 days | 15 minutos            | Visão balanceada              |
| 30 days | 30 minutos            | Visão macro de longo prazo    |

***

## 🏗️ Arquitetura

### 📁 **Estrutura de Arquivos**

```
crypto-core/internal/
├── entity/
│   └── arbitrage-candlestick.go     # Entidades de dados
├── application/candlestick/
│   ├── arbitrage-candlestick-service.go  # Lógica de negócio
│   └── arbitrage-cache.go               # Sistema de cache
└── api/
    └── arbitrage-candlestick-api.go     # Endpoints REST
```

### 🔄 **Fluxo de Dados**

```mermaid theme={null}
graph TD
    A[Requisição API] --> B[Validação Parâmetros]
    B --> C[Verificação Cache]
    C --> D{Cache Existe?}
    D -->|Sim| E[Retorna Dados Cache]
    D -->|Não| F[Busca MongoDB]
    F --> G[Agregação Temporal]
    G --> H[Cálculo Arbitragem]
    H --> I[Salva no Cache]
    I --> J[Retorna Dados]
```

***

## 📋 Estruturas de Dados

### 🎯 **ArbitrageCandlestickData**

```typescript theme={null}
{
  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,
      total_volume: 67500.0,
      spread: 50.0,
      spread_percentage: 0.11
    }
  },
  arbitrage_opportunities: [
    {
      buy_exchange: "binance",
      sell_exchange: "coinbase",
      buy_price: 45050.0,
      sell_price: 45020.0,
      spread: -30.0,
      spread_percentage: -0.07,
      net_profit: -120.07,
      net_profit_percentage: -0.27,
      is_profitable: false,
      liquidity_score: 125.5
    }
  ]
}
```

### 📊 **ArbitrageStatistics**

```typescript theme={null}
{
  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
}
```

***

## 🚀 Como Usar

### 📡 **Endpoint Principal**

```bash theme={null}
GET /v1/candlestick?ticker=BTC-USDT&exchanges=binance,coinbase&period=7%20days
```

### 🔧 **Parâmetros**

| Parâmetro   | Tipo   | Obrigatório | Descrição                                |
| ----------- | ------ | ----------- | ---------------------------------------- |
| `ticker`    | string | Sim         | Par de moedas (ex: "BTC-USDT")           |
| `exchanges` | string | Não         | Lista de exchanges separadas por vírgula |
| `period`    | string | Sim         | Período: "7 days", "15 days", "30 days"  |

### 📝 **Exemplo de Resposta**

```json theme={null}
{
  "ticker": "BTC-USDT",
  "exchanges": ["binance", "coinbase"],
  "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": { /* dados das exchanges */ },
      "arbitrage_opportunities": [ /* oportunidades */ ]
    }
  ],
  "statistics": {
    "total_snapshots": 168,
    "total_opportunities": 5040,
    "profitable_count": 1200,
    "avg_spread_percentage": 0.15,
    "best_exchange_pair": "binance-coinbase"
  }
}
```

***

## 🔍 Análise de Dados

### 📈 **Métricas Disponíveis**

* **Total de Snapshots**: Número de intervalos temporais analisados
* **Oportunidades Totais**: Quantidade total de oportunidades encontradas
* **Taxa de Sucesso**: Percentual de oportunidades lucrativas
* **Spread Médio**: Média dos spreads entre exchanges
* **Melhor Par**: Par de exchanges mais lucrativo
* **Volume Total**: Volume total negociado

### 🎯 **Casos de Uso**

<CardGroup cols={2}>
  <Card title="Backtesting" icon="chart-line">
    Analise estratégias de arbitragem usando dados históricos
  </Card>

  <Card title="Análise de Performance" icon="chart-bar">
    Avalie a performance de diferentes pares de exchanges
  </Card>

  <Card title="Identificação de Padrões" icon="magnifying-glass">
    Descubra padrões temporais nas oportunidades de arbitragem
  </Card>

  <Card title="Otimização de Estratégias" icon="cog">
    Otimize parâmetros baseado em dados históricos
  </Card>
</CardGroup>

***

## ⚡ Performance e Cache

### 🚀 **Sistema de Cache**

* **Duração**: 2 horas por chave
* **Chave**: `arbitrage_candlestick:{ticker}:{exchanges}:{period}`
* **Backend**: Redis ou memória local
* **Invalidação**: Automática por tempo

### 📊 **Otimizações**

<Callout type="info">
  O sistema foi otimizado para:

  * **Busca Eficiente**: Filtros MongoDB otimizados
  * **Agregação em Memória**: Processamento rápido dos dados
  * **Cache Inteligente**: Reduz chamadas ao banco de dados
  * **Dados Históricos**: Não depende de APIs externas
</Callout>

***

## 🔧 Implementação Técnica

### 📊 **Agregação de Dados**

```go theme={null}
// Busca operações do MongoDB
operations := fetchOperationsFromAudit(filter)

// Agrega em snapshots temporais
snapshots := aggregateToSnapshots(operations, exchanges, interval)

// Calcula oportunidades de arbitragem
opportunities := calculateArbitrageOpportunities(exchangeData)
```

### 🎯 **Filtros MongoDB**

```go theme={null}
bsonFilter := bson.M{
    "ticker": filter.Ticker,  // Comparação exata
    "timestamp": bson.M{
        "$gte": primitive.NewDateTimeFromTime(filter.StartTime),
        "$lte": primitive.NewDateTimeFromTime(filter.EndTime),
    },
    "$or": []bson.M{
        {"best_buy_exchange_name": bson.M{"$in": filter.Exchanges}},
        {"best_sell_exchange_name": bson.M{"$in": filter.Exchanges}},
    },
}
```

***

## 📚 Recursos Adicionais

<CardGroup cols={2}>
  <Card title="API Reference" icon="book" href="/api-reference/endpoint/arbitrage-candlestick">
    Documentação completa da API
  </Card>

  <Card title="Exemplos de Uso" icon="code" href="/examples/arbitrage-candlestick">
    Códigos de exemplo e casos de uso
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/troubleshooting/candlestick">
    Soluções para problemas comuns
  </Card>

  <Card title="Changelog" icon="list" href="/changelog/candlestick">
    Histórico de mudanças e melhorias
  </Card>
</CardGroup>

<Callout type="warning">
  **Importante**: Esta funcionalidade utiliza dados históricos da collection `operations_audit`. Certifique-se de que os dados estão sendo coletados regularmente para ter snapshots atualizados.
</Callout>