Como Usar a API da Coinbase: Guia Passo a Passo

A Coinbase, líder global no cenário de exchange de ativos digitais, oferece um conjunto robusto de Interfaces de Programação de Aplicativos (APIs). Essas APIs são a espinha dorsal para desenvolvedores, traders algorítmicos e instituições financeiras que buscam integrar-se programaticamente aos serviços de negociação e dados da Coinbase. Este guia fornece uma exploração técnica detalhada da API Coinbase Exchange, focando na implementação prática, funcionalidades essenciais e melhores práticas operacionais.

💡

Quer uma ótima ferramenta de Teste de API que gera documentação de API bonita?

Quer uma plataforma integrada e completa para sua Equipe de Desenvolvedores trabalhar com máxima produtividade?

Apidog atende a todas as suas demandas e substitui o Postman a um preço muito mais acessível!

botão

Configuração Inicial e Autenticação

A interação bem-sucedida com a API Coinbase Exchange começa com a preparação da conta, o gerenciamento seguro das chaves de API e uma compreensão precisa do protocolo de autenticação.

Pré-requisitos da Conta e Geração de Chave de API

É necessária uma conta Coinbase verificada, tipicamente uma conta Coinbase Advanced Trade ou institucional. As chaves de API são geradas nas configurações da sua conta. Este processo resulta em três informações críticas:

Chave de API (API Key): Uma string pública alfanumérica (ex: k7b9f2d7e8h1g3j4) que identifica sua aplicação.
Segredo de API (API Secret): Uma string privada alfanumérica (ex: S9vP3rK2sLqR7xW1yZ0aB5cD6fE8gH9i). Este segredo é exibido apenas uma vez no momento da geração e deve ser armazenado de forma segura.
Senha (Passphrase): Uma credencial de segurança adicional (ex: mySecureP@$$phr@se2024!) criada por você durante a geração da chave.

As permissões da chave de API são granulares, permitindo restringir ações (ex: somente visualização, execução de negociações, capacidades de saque). Sempre siga o princípio do menor privilégio.

Autenticação de Requisição de API

A API Coinbase Exchange utiliza um mecanismo de autenticação baseado em assinatura (HMAC-SHA256) para todos os endpoints privados e autenticados. Cada requisição requer vários cabeçalhos HTTP personalizados:

CB-ACCESS-KEY: Sua Chave de API.
CB-ACCESS-SIGN: A assinatura HMAC-SHA256 codificada em base64.
CB-ACCESS-TIMESTAMP: Um timestamp Unix epoch atual (em segundos).
CB-ACCESS-PASSPHRASE: A senha da sua Chave de API.

A assinatura (CB-ACCESS-SIGN) é gerada criando um hash HMAC-SHA256 de uma string de pré-hash. A string de pré-hash é uma concatenação de:

O timestamp (como string).
O método HTTP em maiúsculas (ex: GET, POST).
O caminho da requisição (ex: /orders, /products/BTC-USD/book).
O corpo da requisição (para requisições POST; uma string vazia se não houver corpo).

Exemplo de construção da string de pré-hash (para uma requisição POST):

timestamp = str(time.time())
method = "POST"
request_path = "/orders"
body_json_string = '{"product_id": "BTC-USD", "side": "buy", "type": "limit", "price": "50000.00", "size": "0.1"}' // String JSON, não dicionário Python
prehash_string = timestamp + method + request_path + body_json_string

// O Segredo de API precisa ser decodificado de base64 antes de ser usado como chave HMAC.
// secret_decoded = base64.b64decode(api_secret)
// signature = hmac.new(secret_decoded, prehash_string.encode('utf-8'), hashlib.sha256).digest()
// CB_ACCESS_SIGN = base64.b64encode(signature)

Strings de pré-hash construídas incorretamente ou discrepâncias de timestamp (certifique-se de que o relógio do seu servidor esteja sincronizado via NTP) são fontes comuns de erros de autenticação (HTTP 401).

Bibliotecas Cliente e Ambiente de Desenvolvimento

Bibliotecas cliente oficiais e desenvolvidas pela comunidade para linguagens como Python (cbpro), Node.js (coinbase-pro-node), Java e Go abstraem essas complexidades de autenticação. Alternativamente, requisições HTTP diretas podem ser feitas usando ferramentas como curl ou módulos cliente HTTP padrão, exigindo a implementação manual do processo de assinatura.

O Ambiente Sandbox para Testes

A Coinbase oferece um ambiente Sandbox para desenvolvimento e testes, crucial antes de interagir com mercados reais.

Propósito e Funcionalidade

O Sandbox espelha a funcionalidade da API de produção, mas usa fundos de teste e dados de mercado simulados. Ele permite:

Testes sem risco de algoritmos de negociação.
Verificação da lógica de integração da API e tratamento de erros.
Familiarização com as estruturas de requisição/resposta da API.

Principais Diferenças da Produção

Endpoints da API: O Sandbox usa URLs base distintas.
Produção: https://api.exchange.coinbase.com
Sandbox: https://api-public.sandbox.exchange.coinbase.com (Nota: as URLs exatas do Sandbox devem ser sempre confirmadas na documentação oficial).
Chaves de API: Chaves de API separadas devem ser geradas e usadas exclusivamente com o Sandbox.
Dados de Mercado e Liquidez: A profundidade do livro de ofertas, o volume de negociação e os movimentos de preço são simulados. A simulação de preenchimento de ordens pode ser mais simplista e pode não refletir perfeitamente a derrapagem (slippage) ou cenários de preenchimento parcial do mundo real.
Sem Fundos Reais: Todos os ativos e negociações são virtuais. Saldos de teste são tipicamente fornecidos ou podem ser redefinidos.

Transição para Produção

Uma estratégia de implantação robusta inclui configurações distintas para Sandbox e Produção, diferindo principalmente nas credenciais da API e URLs base. Testes completos no Sandbox são primordiais para evitar erros com fundos reais.

Funcionalidades Essenciais da API: Endpoints e Estruturas de Dados

A API é amplamente categorizada em gerenciamento de conta, recuperação de dados de mercado e operações de negociação.

Gerenciamento de Conta

Endpoints para consultar estados e histórico da conta.

Obtendo Saldos da Conta (GET /accounts)
Recupera uma lista de todas as contas de usuário (fiat e cripto) com seus saldos.
Exemplo de Trecho de Resposta para uma conta BTC:

{
  "id": "7532b1f0-20f4-4ba7-96f0-303b592d130f",
  "currency": "BTC",
  "balance": "0.50123456",
  "available": "0.49123456",
  "hold": "0.01000000",
  "profile_id": "sua-string-de-id-de-perfil"
}

balance é o valor total, available é o que pode ser usado para negociação, e hold são fundos reservados para ordens abertas.

Histórico da Conta / Ledger (GET /accounts/{account_id}/ledger)
Fornece uma lista paginada de transações (negociações, taxas, transferências) para uma conta específica.
Parâmetros de Consulta Típicos: before (cursor para paginação), after (cursor), limit (máx. 100, padrão 100), start_date, end_date.
Exemplo de Trecho de Entrada do Ledger:

{
  "id": "1001874",
  "created_at": "2023-10-26T10:00:00.000Z",
  "amount": "-0.00005000",
  "balance": "0.50118456",
  "type": "fee",
  "details": {
    "order_id": "d0c5340b-6d6c-49d9-b567-48c4bfca13d2",
    "product_id": "BTC-USD",
    "trade_id": "7423736"
  }
}

Endpoints de Dados de Mercado

Acesso a informações de mercado em tempo real e históricas.

Produtos / Pares de Negociação (GET /products)
Lista todos os pares de negociação disponíveis e suas propriedades.
Exemplo de Trecho de Produto (BTC-USD):

{
  "id": "BTC-USD",
  "base_currency": "BTC",
  "quote_currency": "USD",
  "base_min_size": "0.0001", // Tamanho mínimo da ordem na moeda base
  "base_max_size": "200.0",  // Tamanho máximo da ordem na moeda base
  "quote_increment": "0.01", // Menor unidade de mudança de preço para a moeda de cotação
  "base_increment": "0.00000001", // Menor unidade de mudança de tamanho para a moeda base
  "display_name": "BTC/USD",
  "min_market_funds": "1",    // Fundos mínimos para uma ordem de mercado na moeda de cotação
  "max_market_funds": "1000000", // Fundos máximos para uma ordem de mercado
  "status": "online",
  "status_message": "",
  "cancel_only": false,
  "limit_only": false,
  "post_only": false,
  "trading_disabled": false
}

Livros de Ofertas (GET /products/{product_id}/book)
Recupera o livro de ofertas atual para um produto.
Parâmetros de Consulta: level (1, 2, ou 3).
* Nível 1: Apenas a melhor oferta de compra (bid) e venda (ask).
* Nível 2: Lista agregada de ofertas de compra e venda em cada nível de preço. (Máx. 50 entradas por lado).
* Nível 3: Livro de ofertas completo com ordens individuais, não agregadas (requer autenticação e pode ter limites de taxa mais rigorosos).
Exemplo de Trecho do Livro de Ofertas Nível 2 (BTC-USD):

{
  "sequence": 1234567890,
  "bids": [
    ["49999.99", "0.75", 3], // [preço, tamanho, número-de-ordens-neste-preço]
    ["49999.98", "1.20", 5]
  ],
  "asks": [
    ["50000.01", "0.50", 2],
    ["50000.02", "1.00", 4]
  ],
  "time": "2023-10-26T10:05:00.123Z"
}

Ticker do Produto (GET /products/{product_id}/ticker)
Informações instantâneas sobre a última negociação (tick), melhor oferta de compra/venda e volume em 24h.
Exemplo de Trecho do Ticker (BTC-USD):

{
  "trade_id": 7423739,
  "price": "50001.50", // Preço da última negociação
  "size": "0.005",    // Tamanho da última negociação
  "bid": "50001.49",
  "ask": "50001.51",
  "volume": "1250.75", // Volume de negociação em 24 horas na moeda base
  "time": "2023-10-26T10:06:15.234Z"
}

Taxas Históricas / Velas (GET /products/{product_id}/candles)
Recupera dados históricos de preços (OHLCV - Abertura, Máxima, Mínima, Fechamento, Volume).
Parâmetros de Consulta: start (timestamp ISO 8601), end (ISO 8601), granularity (em segundos: 60, 300, 900, 3600, 21600, 86400). Máx. 300 velas por requisição.
Exemplo de Dados de Vela (granularidade de 1 hora):

[
  // [tempo, mínima, máxima, abertura, fechamento, volume]
  [1666771200, 49850.25, 50050.75, 49900.00, 50025.10, 15.2345], // tempo é Unix epoch
  [1666767600, 49700.00, 49950.50, 49750.20, 49850.25, 22.6789]
]

Operações de Negociação

Endpoints para colocar, gerenciar e consultar ordens.

Colocando Ordens (POST /orders)
Submete novas ordens para o motor de correspondência (matching engine).
Parâmetros Comuns do Corpo da Requisição:

{
  "client_oid": "meu-id-de-ordem-cliente-unico-001", // Opcional: UUID para idempotência
  "product_id": "BTC-USD",
  "side": "buy", // "buy" (compra) ou "sell" (venda)
  "type": "limit", // "limit", "market", ou "stop" (ordens stop são mais complexas)
  "price": "49500.00", // Necessário para ordens limit
  "size": "0.0125", // Quantidade da moeda base para comprar/vender
  // "funds": "500.00", // Para ordens de mercado de compra: quantidade da moeda de cotação a gastar
  "time_in_force": "GTC", // GTC (Good 'Til Canceled), GTT (Good 'Til Time), IOC (Immediate Or Cancel), FOK (Fill Or Kill)
  // "cancel_after": "min" / "hour" / "day" (usado com GTT)
  "post_only": false, // Se true, a ordem é rejeitada se corresponder imediatamente (garante que seja maker)
  "stp": "dc" // Prevenção de Auto-Negociação (Self-trade prevention): "dc" (Decrease and Cancel), "co" (Cancel Oldest), "cn" (Cancel Newest), "cb" (Cancel Both)
}

Um envio de ordem bem-sucedido retorna os detalhes da ordem, incluindo o id atribuído pelo servidor.

Gerenciando Ordens

Obter Status da Ordem (GET /orders/{order_id_or_client_oid}): Recupera uma única ordem pelo seu ID do servidor ou seu client_oid (prefixe com client: para client_oid, ex: GET /orders/client:meu-id-de-ordem-cliente-unico-001).
Listar Ordens Abertas (GET /orders): Retorna uma lista paginada das suas ordens ativas. Parâmetros como status (open, pending, active) e product_id podem ser usados para filtragem.
Cancelar Ordem (DELETE /orders/{order_id_or_client_oid}): Cancela uma ordem aberta específica. Retorna o ID da ordem após uma solicitação de cancelamento bem-sucedida.
Cancelar Todas as Ordens (DELETE /orders): Cancela todas as ordens abertas, opcionalmente para um product_id específico.

Preenchimentos (Fills) (GET /fills)
Recupera uma lista paginada das suas negociações executadas (preenchimentos).
Parâmetros de Consulta: order_id, product_id, before, after, limit.
Exemplo de Trecho de Preenchimento:

{
  "trade_id": 7423800,
  "product_id": "BTC-USD",
  "price": "49500.00",
  "size": "0.00500000",
  "order_id": "e4f2c1a0-f3d8-4b9b-8b7e-1f2a3c4d5e6f",
  "created_at": "2023-10-26T10:15:30.123Z",
  "liquidity": "T", // "M" para Maker, "T" para Taker
  "fee": "0.00000250", // Taxa na moeda de cotação (USD para BTC-USD) ou moeda base, dependendo da API.
  "settled": true,
  "side": "buy"
}

O Motor de Correspondência (Matching Engine)

O motor de correspondência emparelha ordens de compra e venda com base em um algoritmo de Prioridade Preço-Tempo:

Prioridade de Preço: Ordens com preços mais favoráveis são priorizadas (preço maior para ofertas de compra, preço menor para ofertas de venda).
Prioridade de Tempo: Entre ordens com o mesmo preço, a ordem submetida mais cedo é priorizada.

Ordens Maker vs. Taker:
Maker: Uma ordem que adiciona liquidez ao livro de ofertas (ex: uma ordem limit que não é preenchida imediatamente). Tipicamente beneficia de taxas de negociação mais baixas (ex: 0,00% - 0,40%). O flag post_only ajuda a garantir que uma ordem seja maker.
Taker: Uma ordem que remove liquidez (ex: uma ordem de mercado, ou uma ordem limit que é preenchida imediatamente). Incorre em taxas ligeiramente mais altas (ex: 0,05% - 0,60%). As camadas de taxas são frequentemente baseadas no volume dos últimos 30 dias.

Compreender essa lógica é vital para estratégias de colocação de ordens, gerenciamento de derrapagem (slippage) e otimização de taxas.

Limites de Taxa (Rate Limits) e Throttling

O acesso à API está sujeito a limites de taxa para garantir a estabilidade da plataforma e o uso justo.

Tipos e Identificação

Os limites são tipicamente aplicados por chave de API, por endereço IP, e podem variar por endpoint (ex: endpoints privados autenticados vs. endpoints públicos não autenticados). Endpoints públicos podem ter limites como 3-10 requisições/segundo por IP. Endpoints privados (autenticados) frequentemente têm limites mais altos, também por chave de API.

As respostas da API incluem cabeçalhos indicando o status atual do limite de taxa:

CB-RATELIMIT-LIMIT: O limite total de requisições para a janela atual.
CB-RATELIMIT-REMAINING: Requisições restantes na janela.
CB-RATELIMIT-RESET: Timestamp Unix para quando a janela de limite é redefinida.

Exceder os limites resulta em um erro HTTP 429 Too Many Requests.

Estratégias de Tratamento

Monitoramento Proativo: Verifique CB-RATELIMIT-REMAINING antes de fazer requisições.
Uso Eficiente da API:

Busque apenas os dados necessários.
Use feeds WebSocket para dados em tempo real em vez de fazer polling em endpoints REST.
Armazene em cache dados estáticos ou que mudam com pouca frequência (ex: detalhes de produtos de /products).

Exponential Backoff: Ao receber um erro 429, espere antes de tentar novamente. Implemente um backoff exponencial (ex: espere 1s, depois 2s, 4s, 8s, etc., com jitter) para evitar sobrecarregar o servidor.
WebSockets para Dados em Tempo Real: Para atualizações do livro de ofertas, negociações ao vivo e tickers, conexões WebSocket são significativamente mais eficientes do que polling REST.

Excelência Operacional: Princípios de Runbook

Práticas operacionais robustas são críticas para qualquer integração de API de negociação.

Monitoramento e Alertas

Conectividade e Latência da API: Monitore os tempos de ping e as taxas de sucesso para os endpoints da API.
Consumo de Limite de Taxa: Rastreie CB-RATELIMIT-REMAINING e emita alertas ao se aproximar de zero.
Execução de Ordem: Emita alertas sobre falhas no envio de ordens, ordens presas no status pending além das durações esperadas, ou discrepâncias significativas nos preenchimentos.
Discrepâncias de Saldo: Monitore os saldos das contas chave para desvios inesperados.
Taxas de Erro: Rastreie as porcentagens de erros HTTP 4xx e 5xx; investigue picos. Ferramentas como Prometheus/Grafana ou Datadog são comumente usadas.
Status do Sistema Coinbase: Assine ou verifique regularmente a página de status oficial da Coinbase (ex: status.coinbase.com) para incidentes ou manutenções em toda a plataforma.

Registro (Logging)

Registre informações essenciais para depuração e auditoria:

Timestamp (UTC).
Requisição: método, caminho, cabeçalhos (chave de API redigida), corpo (dados sensíveis redigidos).
Resposta: código de status, cabeçalhos (especialmente limite de taxa e ID da requisição como CB-TRACE-ID), corpo.
IDs de Correlação: Se o seu sistema os utiliza, ou use CB-TRACE-ID dos cabeçalhos de resposta.

Melhores Práticas de Segurança

Segurança da Chave de API: Armazene chaves em cofres seguros (ex: HashiCorp Vault, AWS Secrets Manager) ou variáveis de ambiente. Nunca as codifique diretamente ou as comite para controle de versão.
Whitelisting de IP: Se disponível, restrinja o acesso da chave de API a endereços IP específicos.
Princípio do Menor Privilégio: Conceda às chaves de API apenas as permissões que elas absolutamente necessitam.
Auditorias Regulares: Revise periodicamente o uso e as permissões das chaves de API.
Versionamento da API: Esteja atento às mudanças de versão da API (ex: /v2/products, /v3/products). Monitore os anúncios para desenvolvedores sobre cronogramas de depreciação e caminhos de migração.

Tópicos e Técnicas Avançadas

Feeds WebSocket para Dados em Tempo Real

A Coinbase Exchange fornece feeds WebSocket para dados em tempo real de baixa latência.

Endpoint: Tipicamente uma única URL WebSocket (ex: wss://ws-feed.exchange.coinbase.com).
Assinatura: Após conectar, envie uma mensagem JSON para assinar canais e IDs de produtos.
Exemplo de Mensagem de Assinatura:

{
    "type": "subscribe",
    "product_ids": ["ETH-USD", "BTC-USD"],
    "channels": [
        "level2", // Para atualizações do livro de ofertas Nível 2
        "heartbeat", // Para manter a conexão viva e monitorar o status
        {
            "name": "ticker", // Canal Ticker para produtos específicos
            "product_ids": ["ETH-USD", "BTC-USD"]
        },
        "status" // Para atualizações sobre os status de negociação dos produtos
    ],
    // Para atualizações específicas do usuário (ordens, saldos), a autenticação é necessária dentro do handshake WebSocket ou mensagens iniciais.
    // "signature": "...", "key": "...", "passphrase": "...", "timestamp": "..." (se autenticação for necessária para certos canais)
}

Tipos de Mensagem:

heartbeat: Mensagem periódica para confirmar a saúde da conexão e fornecer status atuais dos produtos.
snapshot: Estado inicial dos dados assinados (ex: snapshot completo do livro de ofertas para level2).
l2update: Mudanças incrementais no livro de ofertas Nível 2 (ofertas de compra/venda adicionadas, alteradas ou removidas).
ticker: Atualizações em tempo real de preço, volume e ofertas de compra/venda.
matches (ou trade): Negociações executadas em tempo real para produtos assinados.
error: Indica um problema com a assinatura ou conexão.
Gerenciar conexões WebSocket envolve lidar com a lógica de reconexão, sequenciamento de mensagens (se aplicável, via números de sequência nas mensagens) e manutenção de estado local (ex: reconstruir um livro de ofertas a partir de mensagens snapshot e l2update).

Idempotência e `client_oid`

Para prevenir envios duplicados de ordens devido a problemas de rede ou retentativas, as requisições POST /orders podem incluir um campo client_oid. Este deve ser um identificador único (ex: UUID v4) gerado pelo seu cliente.

Se uma ordem com um determinado client_oid for recebida e processada, requisições idênticas subsequentes com o mesmo client_oid dentro de um certo período (ex: 24 horas) não criarão uma nova ordem, mas retornarão o status da ordem original.
Isso garante que retentar uma requisição de "colocar ordem" seja seguro.

Prevenção de Auto-Negociação (STP - Self-Trade Prevention)

O parâmetro stp na colocação de ordens (POST /orders) ajuda a prevenir que as ordens de uma conta correspondam entre si. As opções tipicamente incluem:

dc (Decrease and Cancel - Diminuir e Cancelar): A ordem agressiva (taker) é cancelada, e o tamanho da ordem passiva (maker) é diminuído pelo tamanho da ordem agressiva.
co (Cancel Oldest - Cancelar Mais Antiga): A ordem mais antiga é cancelada.
cn (Cancel Newest - Cancelar Mais Nova): A ordem mais nova (agressiva) é cancelada.
cb (Cancel Both - Cancelar Ambas): Ambas as ordens são canceladas.

Conclusão

A API Coinbase Exchange oferece um kit de ferramentas abrangente para desenvolvedores construírem aplicações e integrações de negociação sofisticadas. Dominar sua autenticação, entender suas estruturas de dados, respeitar os limites de taxa e implementar práticas operacionais robustas são chaves para alavancar todo o seu potencial. A mudança para feeds WebSocket para dados em tempo real e recursos como client_oid para idempotência capacitam ainda mais os desenvolvedores a criar sistemas resilientes e eficientes no mundo acelerado da negociação de criptomoedas. A atenção contínua à documentação oficial para desenvolvedores da Coinbase é crucial para se manter atualizado sobre novos recursos, mudanças de endpoint e melhores práticas.