Blog

Como Usar a API da Coinbase: Guia Passo a Passo

Rebecca Kovács

Rebecca Kovács

27 maio 2025

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:

  1. Chave de API (API Key): Uma string pública alfanumérica (ex: k7b9f2d7e8h1g3j4) que identifica sua aplicação.
  2. 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.
  3. 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:

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:

  1. O timestamp (como string).
  2. O método HTTP em maiúsculas (ex: GET, POST).
  3. O caminho da requisição (ex: /orders, /products/BTC-USD/book).
  4. 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:

Principais Diferenças da Produção

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

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:

  1. 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).
  2. Prioridade de Tempo: Entre ordens com o mesmo preço, a ordem submetida mais cedo é priorizada.

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:

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

Estratégias de Tratamento

  1. Monitoramento Proativo: Verifique CB-RATELIMIT-REMAINING antes de fazer requisições.
  2. Uso Eficiente da API:
  1. 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.
  2. 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

Registro (Logging)

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

Melhores Práticas de Segurança

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.

{
    "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:

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.

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:

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.

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar