MercadoBitcoin.Client 1.0.2

MercadoBitcoin.Client

Uma biblioteca .NET 9 completa e moderna para integração com a API v4 do Mercado Bitcoin. Esta biblioteca oferece acesso a todos os endpoints disponíveis da plataforma, incluindo dados públicos, trading, gestão de contas e operações de carteira, com suporte nativo ao HTTP/2 para máxima performance.

🚀 Características

• ✅ Cobertura Completa: Todos os endpoints da API v4 do Mercado Bitcoin
• ✅ .NET 9: Framework mais recente com performance otimizada
• ✅ HTTP/2 Nativo: Protocolo HTTP/2 por padrão para máxima performance
• ✅ Async/Await: Programação assíncrona nativa
• ✅ Strongly Typed: Modelos de dados tipados para type safety
• ✅ OpenAPI Integration: Cliente gerado automaticamente via NSwag
• ✅ Clean Architecture: Código organizado e maintível
• ✅ Error Handling: Sistema robusto de tratamento de erros
• ✅ Retry Policies: Políticas de retry com Polly para maior robustez
• ✅ Rate Limit Compliant: Respeita os limites da API
• ✅ Production Ready: Pronto para uso em produção

📦 Instalação

# Via Package Manager Console
Install-Package MercadoBitcoin.Client

# Via .NET CLI
dotnet add package MercadoBitcoin.Client

# Via PackageReference
<PackageReference Include="MercadoBitcoin.Client" Version="1.0.1" />

🔧 Configuração

Configuração Básica

using MercadoBitcoin.Client;

// Configuração simples
var client = new MercadoBitcoinClient();

// Configuração com HTTP/2 (padrão)
var client = MercadoBitcoinClient.CreateWithHttp2();

// Configuração com retry policies
var client = MercadoBitcoinClient.CreateWithRetryPolicy();

Configuração Avançada com HTTP/2

A biblioteca utiliza HTTP/2 por padrão para máxima performance. Você pode configurar o protocolo HTTP através do appsettings.json:

{
  "MercadoBitcoin": {
    "BaseUrl": "https://api.mercadobitcoin.net/api/v4",
    "HttpVersion": "2.0",
    "EnableRetryPolicy": true,
    "MaxRetryAttempts": 3,
    "RetryDelaySeconds": 1
  }
}

Configuração com Injeção de Dependência

// Program.cs ou Startup.cs
services.AddMercadoBitcoinClient(options =>
{
    options.BaseUrl = "https://api.mercadobitcoin.net/api/v4";
    options.HttpVersion = HttpVersion.Version20; // HTTP/2 por padrão
    options.EnableRetryPolicy = true;
});

🔄 Retry Policies e HTTP/2

A biblioteca implementa políticas de retry robustas com Polly e utiliza HTTP/2 por padrão para máxima performance:

Características do HTTP/2

• Multiplexing: Múltiplas requisições simultâneas em uma única conexão
• Header Compression: Compressão HPACK para reduzir overhead
• Server Push: Suporte a push de recursos (quando disponível)
• Binary Protocol: Protocolo binário mais eficiente que HTTP/1.1

Políticas de Retry

• Exponential Backoff: Delay crescente entre tentativas
• Circuit Breaker: Proteção contra falhas em cascata
• Timeout Handling: Timeouts configuráveis por operação
• Rate Limit Aware: Respeita os limites da API automaticamente

Configuração Básica com Retry

using MercadoBitcoin.Client;
// Criar cliente com retry policies
var client = MercadoBitcoinClientExtensions.CreateWithRetryPolicies();

// Autenticar
await client.AuthenticateAsync("seu_login", "sua_senha");

// Configuração personalizada de retry
var client = MercadoBitcoinClient.CreateWithRetryPolicy(options =>
{
    options.MaxRetryAttempts = 5;
    options.RetryDelaySeconds = 2;
    options.UseExponentialBackoff = true;
    options.HttpVersion = HttpVersion.Version20; // HTTP/2
});

Configurações de Retry Personalizadas

using MercadoBitcoin.Client.Http;

// Configuração para trading (mais agressiva)
var tradingConfig = MercadoBitcoinClientExtensions.CreateTradingRetryConfig();
// 5 tentativas, delay inicial de 0.5s, backoff de 1.5x, máximo 10s

// Configuração para dados públicos (mais conservadora)
var publicConfig = MercadoBitcoinClientExtensions.CreatePublicDataRetryConfig();
// 2 tentativas, delay inicial de 2s, backoff de 2x, máximo 30s

// Configuração customizada
var customConfig = new RetryPolicyConfig
{
    MaxRetryAttempts = 3,
    BaseDelaySeconds = 1.0,
    BackoffMultiplier = 2.0,
    MaxDelaySeconds = 30.0,
    RetryOnTimeout = true,
    RetryOnRateLimit = true,
    RetryOnServerErrors = true
};

Cenários de Retry

O sistema automaticamente faz retry nos seguintes casos:

• ⏱️ Timeouts (RequestTimeout)
• 🚦 Rate Limiting (TooManyRequests - 429)
• 🔥 Erros de Servidor (5xx - InternalServerError, BadGateway, ServiceUnavailable, GatewayTimeout)
• 🌐 Falhas de Rede (HttpRequestException, TaskCanceledException)

Recuperação Automática

O sistema automaticamente se recupera de falhas temporárias através das políticas de retry, proporcionando maior robustez às aplicações que utilizam a biblioteca.

🏗️ Arquitetura

MercadoBitcoin.Client/
├── 📁 Public Data      → Dados públicos (tickers, orderbook, trades, candles)
├── 📁 Account          → Gestão de contas (saldos, tier, posições, taxas)
├── 📁 Trading          → Operações de trading (ordens, execuções, cancelamentos)
├── 📁 Wallet           → Carteira (depósitos, saques, endereços, limites)
└── 📁 Authentication   → Sistema de autenticação Bearer Token

📊 Endpoints Suportados

🔓 Dados Públicos

🔐 Conta e Autenticação

📈 Trading

💰 Carteira

💻 Exemplos de Uso

Configuração Inicial

using MercadoBitcoin.Client;

// Cliente para dados públicos (sem autenticação)
var client = new MercadoBitcoinClient();

// Cliente autenticado
var authenticatedClient = new MercadoBitcoinClient();
await authenticatedClient.AuthenticateAsync("seu_api_token_id", "seu_api_token_secret");

📊 Dados Públicos

// Obter lista de todos os símbolos disponíveis
var symbols = await client.GetSymbolsAsync();
Console.WriteLine($"Símbolos disponíveis: {symbols.Symbol.Count}");

// Obter ticker do Bitcoin
var tickers = await client.GetTickersAsync("BTC-BRL");
var btcTicker = tickers.First();
Console.WriteLine($"BTC: R$ {btcTicker.Last}");

// Obter livro de ofertas
var orderBook = await client.GetOrderBookAsync("BTC-BRL", limit: "10");
Console.WriteLine($"Melhor oferta de compra: R$ {orderBook.Bids[0][0]}");
Console.WriteLine($"Melhor oferta de venda: R$ {orderBook.Asks[0][0]}");

// Obter histórico de negociações
var trades = await client.GetTradesAsync("BTC-BRL", limit: 100);
Console.WriteLine($"Últimas {trades.Count} negociações obtidas");

// Obter dados de candles/gráficos
var to = DateTimeOffset.Now.ToUnixTimeSeconds();
var candles = await client.GetCandlesAsync("BTC-BRL", "1h", (int)to, countback: 24);
Console.WriteLine($"OHLCV das últimas 24 horas obtidas");

// Obter taxas de retirada de um ativo
var fees = await client.GetAssetFeesAsync("BTC");
Console.WriteLine($"Taxa de retirada BTC: {fees.Withdrawal_fee}");

// Obter redes disponíveis para um ativo
var networks = await client.GetAssetNetworksAsync("USDC");
foreach (var network in networks)
{
    Console.WriteLine($"USDC disponível na rede: {network.Network}");
}

👤 Gestão de Conta

// Obter informações das contas
var accounts = await authenticatedClient.GetAccountsAsync();
var account = accounts.First();
Console.WriteLine($"Conta: {account.Name} ({account.Currency})");

// Obter saldos
var balances = await authenticatedClient.GetBalancesAsync(account.Id);
foreach (var balance in balances)
{
    Console.WriteLine($"{balance.Symbol}: {balance.Available} (disponível) + {balance.On_hold} (reservado)");
}

// Obter tier de taxas
var tier = await authenticatedClient.GetTierAsync(account.Id);
Console.WriteLine($"Tier atual: {tier.First().Tier}");

// Obter taxas de trading para um símbolo
var tradingFees = await authenticatedClient.GetTradingFeesAsync(account.Id, "BTC-BRL");
Console.WriteLine($"Taxa maker: {tradingFees.Maker_fee}% | Taxa taker: {tradingFees.Taker_fee}%");

// Obter posições abertas
var positions = await authenticatedClient.GetPositionsAsync(account.Id);
foreach (var position in positions)
{
    Console.WriteLine($"Posição {position.Side} {position.Instrument}: {position.Qty} @ R$ {position.AvgPrice}");
}

📈 Trading

var accountId = accounts.First().Id;

// Criar ordem de compra limitada
var buyOrder = new PlaceOrderRequest
{
    Side = "buy",
    Type = "limit",
    Qty = "0.001",              // Quantidade em BTC
    LimitPrice = 280000,        // Preço limite em R$
    ExternalId = "minha-ordem-001"
};

var placedOrder = await authenticatedClient.PlaceOrderAsync("BTC-BRL", accountId, buyOrder);
Console.WriteLine($"Ordem criada: {placedOrder.OrderId}");

// Criar ordem de venda com stop-loss
var sellOrderWithStop = new PlaceOrderRequest
{
    Side = "sell",
    Type = "stoplimit",
    Qty = "0.001",
    LimitPrice = 270000,        // Preço de venda
    StopPrice = 275000          // Preço de ativação do stop
};

var stopOrder = await authenticatedClient.PlaceOrderAsync("BTC-BRL", accountId, sellOrderWithStop);

// Listar ordens abertas
var openOrders = await authenticatedClient.ListOrdersAsync("BTC-BRL", accountId, status: "working");
Console.WriteLine($"Você tem {openOrders.Count} ordens abertas");

// Consultar uma ordem específica
var orderDetail = await authenticatedClient.GetOrderAsync("BTC-BRL", accountId, placedOrder.OrderId);
Console.WriteLine($"Status da ordem: {orderDetail.Status}");
Console.WriteLine($"Quantidade executada: {orderDetail.FilledQty}");

// Cancelar uma ordem
var cancelResult = await authenticatedClient.CancelOrderAsync(accountId, "BTC-BRL", placedOrder.OrderId);
Console.WriteLine($"Cancelamento: {cancelResult.Status}");

// Listar todas as ordens (todos os símbolos)
var allOrders = await authenticatedClient.ListAllOrdersAsync(accountId, status: "filled", size: "50");
Console.WriteLine($"Você tem {allOrders.Items.Count} ordens executadas");

// Cancelar todas as ordens abertas (cuidado!)
// var cancelAll = await authenticatedClient.CancelAllOpenOrdersByAccountAsync(accountId);

💰 Operações de Carteira

// Obter endereço para depósito de Bitcoin
var btcAddress = await authenticatedClient.GetDepositAddressesAsync(accountId, "BTC");
Console.WriteLine($"Endereço BTC: {btcAddress.Addresses.First().Hash}");

// Obter endereço para depósito de USDC na rede Ethereum
var usdcAddress = await authenticatedClient.GetDepositAddressesAsync(accountId, "USDC", Network2.Ethereum);
Console.WriteLine($"Endereço USDC (ETH): {usdcAddress.Addresses.First().Hash}");

// Listar histórico de depósitos
var deposits = await authenticatedClient.ListDepositsAsync(accountId, "BTC", limit: "10");
foreach (var deposit in deposits)
{
    Console.WriteLine($"Depósito: {deposit.Amount} {deposit.Coin} - Status: {deposit.Status}");
}

// Listar depósitos fiat (BRL)
var fiatDeposits = await authenticatedClient.ListFiatDepositsAsync(accountId, "BRL", limit: "10");
foreach (var deposit in fiatDeposits)
{
    Console.WriteLine($"Depósito PIX: R$ {deposit.Amount} - Status: {deposit.Status}");
}

// Solicitar saque de Bitcoin
var withdrawRequest = new WithdrawCoinRequest
{
    Address = "bc1qs62xef6x0tyxsz87fya6le7htc6q5wayhqdzen",
    Quantity = "0.001",
    Tx_fee = "0.00005",
    Description = "Saque para carteira pessoal",
    Network = "bitcoin"
};

var withdraw = await authenticatedClient.WithdrawCoinAsync(accountId, "BTC", withdrawRequest);
Console.WriteLine($"Saque solicitado: ID {withdraw.Id}");

// Solicitar saque em Reais para conta bancária
var brlWithdrawRequest = new WithdrawCoinRequest
{
    Account_ref = 1,              // ID da conta bancária cadastrada
    Quantity = "1000.00",
    Description = "Saque para conta corrente"
};

var brlWithdraw = await authenticatedClient.WithdrawCoinAsync(accountId, "BRL", brlWithdrawRequest);

// Listar histórico de saques
var withdrawals = await authenticatedClient.ListWithdrawalsAsync(accountId, "BTC", page: 1, page_size: 10);
foreach (var withdrawal in withdrawals)
{
    Console.WriteLine($"Saque: {withdrawal.Net_quantity} {withdrawal.Coin} - Status: {withdrawal.Status}");
}

// Consultar saque específico
var withdrawalDetail = await authenticatedClient.GetWithdrawalAsync(accountId, "BTC", withdraw.Id.ToString());
Console.WriteLine($"Status: {withdrawalDetail.Status} | TX: {withdrawalDetail.Tx}");

// Obter limites de saque
var limits = await authenticatedClient.GetWithdrawLimitsAsync(accountId, symbols: "BTC,ETH,BRL");
Console.WriteLine("Limites de saque disponíveis obtidos");

// Obter configurações de saque BRL
var brlConfig = await authenticatedClient.GetBrlWithdrawConfigAsync(accountId);
Console.WriteLine($"Limite mínimo BRL: R$ {brlConfig.Limit_min}");
Console.WriteLine($"Limite máximo poupança: R$ {brlConfig.Saving_limit_max}");

// Listar endereços de carteira cadastrados
var walletAddresses = await authenticatedClient.GetWithdrawCryptoWalletAddressesAsync(accountId);
foreach (var address in walletAddresses)
{
    Console.WriteLine($"{address.Asset}: {address.Address}");
}

// Listar contas bancárias cadastradas
var bankAccounts = await authenticatedClient.GetWithdrawBankAccountsAsync(accountId);
foreach (var account in bankAccounts)
{
    Console.WriteLine($"{account.Bank_name}: {account.Recipient_name} - {account.Account_type}");
}

⚡ Rate Limits

A biblioteca respeita automaticamente os rate limits da API do Mercado Bitcoin:

• Dados Públicos: 1 request/segundo
• Trading: 3 requests/segundo (criação/cancelamento), 10 requests/segundo (consultas)
• Conta: 3 requests/segundo
• Carteira: Varia por endpoint
• Cancel All Orders: 1 request/minuto

🔒 Segurança

Autenticação

• Utiliza o sistema de Bearer Token do Mercado Bitcoin
• Tokens são gerenciados automaticamente pela biblioteca
• Suporte a renovação automática de tokens

Boas Práticas

• Nunca exponha suas credenciais de API em código fonte
• Use variáveis de ambiente ou Azure Key Vault para credenciais
• Implemente retry policies com backoff exponencial
• Configure timeouts apropriados

// ✅ Bom
var apiKey = Environment.GetEnvironmentVariable("MB_API_KEY");
var apiSecret = Environment.GetEnvironmentVariable("MB_API_SECRET");
await client.AuthenticateAsync(apiKey, apiSecret);

// ❌ Ruim
await client.AuthenticateAsync("hardcoded_key", "hardcoded_secret");

🔧 Configuração Avançada

Configuração de HTTP Version

A biblioteca suporta tanto HTTP/1.1 quanto HTTP/2. Por padrão, utiliza HTTP/2 para máxima performance:

// HTTP/2 (padrão - recomendado)
var client = MercadoBitcoinClient.CreateWithHttp2();

// HTTP/1.1 (para compatibilidade)
var client = MercadoBitcoinClient.CreateWithHttp11();

// Configuração via appsettings.json
{
  "MercadoBitcoin": {
    "HttpVersion": "2.0", // ou "1.1"
    "BaseUrl": "https://api.mercadobitcoin.net/api/v4"
  }
}

Performance e Otimizações

Com HTTP/2, a biblioteca oferece:

• Até 50% menos latência em requisições múltiplas
• Redução de 30% no uso de banda através de compressão de headers
• Conexões persistentes com multiplexing
• Melhor utilização de recursos do servidor

Configuração de Timeout

var client = new MercadoBitcoinClient();
client.HttpClient.Timeout = TimeSpan.FromSeconds(30);

🚨 Tratamento de Erros

try
{
    var orderResult = await client.PlaceOrderAsync("BTC-BRL", accountId, orderRequest);
}
catch (MercadoBitcoinApiException ex)
{
    Console.WriteLine($"Erro da API: {ex.Code} - {ex.Message}");
    
    // Tratar erros específicos
    switch (ex.Code)
    {
        case "INSUFFICIENT_BALANCE":
            Console.WriteLine("Saldo insuficiente para a operação");
            break;
        case "INVALID_SYMBOL":
            Console.WriteLine("Símbolo inválido");
            break;
        case "ORDER_NOT_FOUND":
            Console.WriteLine("Ordem não encontrada");
            break;
        default:
            Console.WriteLine($"Erro não tratado: {ex.Code}");
            break;
    }
}
catch (HttpRequestException ex)
{
    Console.WriteLine($"Erro de rede: {ex.Message}");
}
catch (TaskCanceledException ex)
{
    Console.WriteLine($"Timeout: {ex.Message}");
}

🧪 Testes

Executando os Testes

# Executar todos os testes
dotnet test

# Executar testes com cobertura
dotnet test --collect:"XPlat Code Coverage"

# Testar todas as rotas (exemplo incluído)
dotnet run --project TestAllRoutes

Teste de Performance HTTP/2 vs HTTP/1.1

A biblioteca inclui testes de performance que demonstram as vantagens do HTTP/2:

// Exemplo de teste de performance
var http2Client = MercadoBitcoinClient.CreateWithHttp2();
var http11Client = MercadoBitcoinClient.CreateWithHttp11();

// Teste com múltiplas requisições simultâneas
var tasks = new List<Task>();
for (int i = 0; i < 10; i++)
{
    tasks.Add(http2Client.GetSymbolsAsync()); // HTTP/2 - mais rápido
    tasks.Add(http11Client.GetSymbolsAsync()); // HTTP/1.1 - mais lento
}

await Task.WhenAll(tasks);

Configuração de Testes

Para executar testes que requerem autenticação, configure as variáveis de ambiente:

export MERCADO_BITCOIN_API_ID="seu_api_id"
export MERCADO_BITCOIN_API_SECRET="seu_api_secret"

📚 Documentação Adicional

• API v4 do Mercado Bitcoin - Documentação oficial da API
• HTTP/2 RFC 7540 - Especificação do protocolo HTTP/2
• Polly Documentation - Biblioteca de resilience patterns
• .NET 9 Performance - Melhorias de performance no .NET 9
• NSwag Documentation - Geração de clientes OpenAPI

Recursos Adicionais

• Swagger/OpenAPI: Cliente gerado automaticamente a partir da especificação OpenAPI
• Rate Limiting: Implementação automática de rate limiting conforme especificação da API
• Error Handling: Sistema robusto de tratamento de erros com tipos específicos
• Logging: Suporte completo a logging com Microsoft.Extensions.Logging
• Dependency Injection: Integração nativa com DI container do .NET

Migração e Atualizações

Migração para HTTP/2

Se você está migrando de uma versão anterior que usava HTTP/1.1:

// Antes (HTTP/1.1)
var client = new MercadoBitcoinClient();

// Depois (HTTP/2 - recomendado)
var client = MercadoBitcoinClient.CreateWithHttp2();

// Ou manter HTTP/1.1 se necessário
var client = MercadoBitcoinClient.CreateWithHttp11();

Remoção do WebSocket

Importante: A partir desta versão, o suporte a WebSocket foi removido. A biblioteca agora foca exclusivamente em HTTP/2 para máxima performance e simplicidade. Se você precisar de dados em tempo real, recomendamos:

1. Polling otimizado com HTTP/2 (mais eficiente que WebSocket em muitos casos)
2. Server-Sent Events (se suportado pela API no futuro)
3. Bibliotecas especializadas para WebSocket se absolutamente necessário

• OpenAPI Specification
• Taxas e Limites
• Central de Ajuda

🤝 Contribuição

Contribuições são bem-vindas! Por favor, siga estas diretrizes:

Desenvolvimento

1. Fork o repositório
2. Clone seu fork localmente
3. Configure o ambiente de desenvolvimento:

# Instalar dependências
dotnet restore

# Configurar HTTP/2 (padrão)
# Não é necessária configuração adicional

# Executar testes
dotnet test

4. Crie uma branch para sua feature:

git checkout -b feature/nova-funcionalidade

5. Implemente suas mudanças seguindo os padrões:

   • Use HTTP/2 por padrão
   • Mantenha compatibilidade com HTTP/1.1
   • Adicione testes para novas funcionalidades
   • Siga as convenções de código existentes
   • Documente mudanças no README

6. Teste suas mudanças:

# Testes unitários
dotnet test

# Teste de integração
dotnet run --project TestAllRoutes

# Teste de performance HTTP/2
dotnet run --project PerformanceTests

7. Commit e push:

git commit -m "feat: adicionar nova funcionalidade HTTP/2"
git push origin feature/nova-funcionalidade

8. Abra um Pull Request

Padrões de Código

• C# 12 com nullable reference types
• Async/await para operações I/O
• HTTP/2 como padrão
• Clean Architecture principles
• SOLID principles
• Unit tests com cobertura > 80%

Tipos de Contribuição

• 🐛 Bug fixes
• ✨ Novas funcionalidades
• 📚 Documentação
• 🚀 Melhorias de performance
• 🧪 Testes
• 🔧 Configurações e tooling

📄 Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.

⚠️ Disclaimer

Esta biblioteca não é oficial e não é afiliada ao Mercado Bitcoin. Use por sua própria conta e risco.

Importante sobre HTTP/2

• Compatibilidade: HTTP/2 é suportado por todos os servidores modernos, incluindo a API do Mercado Bitcoin
• Fallback: A biblioteca automaticamente faz fallback para HTTP/1.1 se HTTP/2 não estiver disponível
• Performance: HTTP/2 oferece melhor performance, especialmente para múltiplas requisições
• Segurança: HTTP/2 requer TLS por padrão, aumentando a segurança das comunicações

Remoção do WebSocket

A partir desta versão, removemos o suporte a WebSocket para focar em:

• Simplicidade: Menos complexidade de código e manutenção
• Performance: HTTP/2 com multiplexing é mais eficiente para a maioria dos casos
• Confiabilidade: HTTP é mais confiável que WebSocket em redes instáveis
• Padrão da indústria: Muitas APIs modernas estão migrando de WebSocket para HTTP/2

Responsabilidades do Usuário

• Testes: Sempre teste em ambiente de desenvolvimento antes de usar em produção
• Rate Limits: Respeite os limites da API para evitar bloqueios
• Segurança: Mantenha suas credenciais seguras e use HTTPS
• Atualizações: Mantenha a biblioteca atualizada para correções de segurança
• Monitoramento: Monitore suas aplicações para detectar problemas rapidamente

Desenvolvido com ❤️ para a comunidade .NET brasileira

Última atualização: Janeiro 2025 - Versão HTTP/2