Como Usar a API da Kraken: Guia Completo para Negociação

Imagine ter acesso a uma das exchanges de criptomoedas mais líquidas do mundo por meio de uma API testada e comprovada que gerencia contratos futuros e negociação à vista. A Kraken oferece exatamente isso, disponibilizando interfaces WebSocket e REST para uma exchange que foi estabelecida em 2011 e atende mais de 10 milhões de usuários em 190 países com ampla liquidez em mais de 200 pares de negociação.

As APIs de negociação de criptomoedas se dividem em duas categorias: aquelas projetadas para conveniência do varejo e aquelas construídas para confiabilidade institucional. Muitas exchanges priorizam aplicativos móveis em detrimento da estabilidade da API, resultando em limites de taxa que sufocam estratégias algorítmicas e documentação que fica atrás dos lançamentos de recursos. A Kraken elimina esses pontos de atrito, oferecendo acesso à API em camadas com base no volume de negociação, ambientes de sandbox abrangentes e endpoints dedicados para traders de alta frequência. Você constrói estratégias automatizadas que escalam de scripts de hobbystas a sistemas de nível institucional.

Sumário:

• Entendendo a Arquitetura da API da Kraken
• Autenticação e Configuração da Chave da API
• Negociação à Vista (Spot Trading) com API REST
• Dados em Tempo Real com WebSocket
• Negociação de Futuros e Recursos Avançados
• Conclusão

Entendendo a Arquitetura da API da Kraken

A Kraken opera três ecossistemas de API distintos: Spot REST, Futures REST e WebSocket. Entender essas arquiteturas ajuda você a escolher o caminho de integração correto.

API REST Spot

A API REST Spot fornece acesso à funcionalidade central da exchange Kraken. Ela é organizada em endpoints públicos (dados de mercado, informações de ticker, profundidade do livro de ordens) e endpoints privados (saldo da conta, gerenciamento de ordens, financiamento). Todas as solicitações usam HTTPS com TLS 1.2 ou superior.

Base URL: https://api.kraken.com/0

Endpoints públicos não exigem autenticação. Endpoints privados usam assinatura de solicitação HMAC-SHA512 com chaves de API. Os formatos de resposta variam — alguns endpoints retornam arrays onde o primeiro elemento é uma string de erro (design legado), enquanto endpoints mais recentes usam objetos JSON padrão.

API REST de Futuros

A Kraken Futures opera separadamente da exchange spot com sua própria infraestrutura de API. Ela suporta swaps perpétuos e futuros de vencimento fixo em criptomoedas com alavancagem de até 50x.

Base URLs:

• Produção: https://futures.kraken.com/api/v3
• Sandbox: https://demo-futures.kraken.com/api/v3

A API de Futuros usa mecanismos de autenticação e estruturas de endpoint diferentes em comparação com a Spot. Você precisa de chaves de API separadas geradas em futures.kraken.com, distintas de suas credenciais de negociação spot.

API WebSocket

A Kraken fornece fluxos de dados em tempo real por meio de dois servidores WebSocket:

• Público: wss://ws.kraken.com — Dados de mercado, livros de ordens, negociações
• Privado: wss://ws-auth.kraken.com — Atualizações de conta, status de ordens, mudanças de saldo

Diferente do polling REST, as conexões WebSocket enviam dados assim que ficam disponíveis, reduzindo a latência de centenas de milissegundos para dezenas de milissegundos. O servidor público não exige autenticação; o servidor privado requer um token WebSocket obtido via API REST.

Limite de Taxa

A Kraken implementa um limite de taxa baseado em níveis:

• Inicial (Starter): 60 chamadas por minuto (público), 30 chamadas por minuto (privado)
• Intermediário (Intermediate): 125 chamadas por minuto (público), 60 chamadas por minuto (privado)
• Pro: Mais de 250 chamadas por minuto com base no volume de negociação de 30 dias

Exceder os limites resulta em erros HTTP 429 com cabeçalhos Retry-After indicando quando você pode retomar as solicitações.

Autenticação e Configuração da Chave da API

A Kraken usa autenticação HMAC-SHA512 com proteção de repetição baseada em nonce. Isso requer implementação cuidadosa para evitar erros de "nonce inválido" comuns em aplicações multi-thread.

Gerando Chaves de API

Navegue para Conta → Segurança → API no seu painel da Kraken:

1. Clique em "Gerar Nova Chave"
2. Selecione as permissões:

• Consulta (Query): Ler saldo da conta, ordens abertas, histórico de negociações
• Negociação (Trade): Fazer e cancelar ordens
• Retirada (Withdraw): Transferir fundos (use com cautela)
• Depósito (Deposit): Visualizar endereços e métodos de depósito

3.  Especifique o whitelisting de IP (recomendado para produção)

4.  Armazene a Chave de API e a Chave Privada com segurança — a Kraken nunca mais exibe a Chave Privada

Para negociação de Futuros, repita este processo em futures.kraken.com/settings/api. O ambiente de sandbox em demo-futures.kraken.com usa credenciais separadas.

Assinatura HMAC-SHA512 (Implementação Manual)

Se não estiver usando um SDK, implemente a autenticação da seguinte forma:

import requests
import hmac
import hashlib
import base64
import time
import json

class KrakenAuth:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = base64.b64decode(api_secret)
        self.base_url = "https://api.kraken.com"
    
    def generate_signature(self, urlpath, data):
        # Nonce must be higher than any previous nonce used
        nonce = str(int(time.time() * 1000))
        data['nonce'] = nonce
        
        # Create message: nonce + POST data
        message = nonce + json.dumps(data, separators=(',', ':'))
        
        # Create HMAC-SHA512 signature
        signature = hmac.new(
            self.api_secret,
            urlpath.encode() + hashlib.sha256(message.encode()).digest(),
            hashlib.sha512
        ).hexdigest()
        
        return {
            'API-Key': self.api_key,
            'API-Sign': signature,
            'Content-Type': 'application/x-www-form-urlencoded'
        }, data
    
    def private_request(self, method, params=None):
        urlpath = f'/0/private/{method}'
        data = params or {}
        
        headers, signed_data = self.generate_signature(urlpath, data)
        
        response = requests.post(
            f"{self.base_url}{urlpath}",
            headers=headers,
            data=signed_data
        )
        
        return response.json()

# Usage
kraken = KrakenAuth(
    api_key="YOUR_API_KEY",
    api_secret="YOUR_BASE64_ENCODED_PRIVATE_KEY"
)

# Get account balance
balance = kraken.private_request('Balance')
print(balance)

Crítico: Gerenciamento de Nonce

A Kraken exige nonces estritamente crescentes por chave de API. Se você tiver várias threads ou processos usando a mesma chave, eles entrarão em conflito e gerarão erros "EAPI:Invalid nonce". Soluções:

1. Use chaves de API diferentes para cada algoritmo ou serviço de negociação
2. Implemente a sincronização de nonce via Redis ou banco de dados se o compartilhamento de chaves for inevitável
3. Use timestamps com precisão de microssegundos (multiplique o tempo Unix por 1000) para reduzir a probabilidade de colisão

SDKs Oficiais

A Kraken fornece SDKs oficiais para Python e Node.js, com SDKs da comunidade para Go, Rust, Julia e outras linguagens:

# Python
pip install python-kraken-sdk

# Node.js
npm install @kraken-api/sdk

Os SDKs oficiais lidam com autenticação, gerenciamento de nonce e análise de erros automaticamente. Use-os, a menos que você tenha requisitos específicos para manipulação HTTP personalizada.

Negociação à Vista (Spot Trading) com API REST

A API REST Spot fornece funcionalidade de negociação abrangente por meio de endpoints bem documentados.

Dados de Mercado (Públicos)

Recupere os pares de negociação disponíveis:

curl "https://api.kraken.com/0/public/AssetPairs"

Obtenha informações de ticker:

curl "https://api.kraken.com/0/public/Ticker?pair=XBTUSD"

A Kraken usa símbolos de par não padronizados — XBT em vez de BTC para Bitcoin, XXBT em alguns endpoints legados, ZUSD em vez de USD. Sempre verifique os códigos dos ativos usando o endpoint AssetPairs antes de negociar.

Busque a profundidade do livro de ordens:

curl "https://api.kraken.com/0/public/Depth?pair=XBTUSD&count=10"

Saldo da Conta (Privado)

balance = kraken.private_request('Balance')
print(balance)

O formato da resposta usa códigos de ativos como chaves (ZUSD para USD, XXBT para Bitcoin):

{
  "error": [],
  "result": {
    "ZUSD": "1000.50",
    "XXBT": "0.2500"
  }
}

Realizando Ordens

Faça uma ordem de compra limitada:

order = kraken.private_request('AddOrder', {
    'pair': 'XBTUSD',
    'type': 'buy',
    'ordertype': 'limit',
    'price': '65000.00',
    'volume': '0.01',
    'oflags': 'post'  # Post-only flag
})

print(order)

Os tipos de ordem incluem:

• market: Executa imediatamente ao melhor preço disponível
• limit: Executa ao preço especificado ou melhor
• stop-loss: Aciona uma ordem de mercado quando o preço cruza um limite
• take-profit: Oposto de stop-loss
• trailing-stop: Stop dinâmico que segue os movimentos de preço

Gerenciamento de Ordens

Liste as ordens abertas:

open_orders = kraken.private_request('OpenOrders')
print(open_orders)

Cancele uma ordem:

kraken.private_request('CancelOrder', {
    'txid': 'XXXXXX-XXXXXX-XXXXXX'
})

Cancele todas as ordens (parada de emergência):

kraken.private_request('CancelAll')

Histórico de Negociações

Consulte as negociações executadas:

trades = kraken.private_request('TradesHistory', {
    'start': '1704067200',  # Unix timestamp
    'end': '1706659200'
})

Dica ProfissionalApidog

Dados em Tempo Real com WebSocket

O polling REST introduz uma latência inaceitável para negociação algorítmica. A API WebSocket da Kraken transmite atualizações em tempo real do livro de ordens, negociações e eventos de conta.

Conectando-se ao WebSocket Público

const WebSocket = require('ws');

const ws = new WebSocket('wss://ws.kraken.com');

ws.on('open', () => {
  console.log('Connected to Kraken public WebSocket');
  
  // Subscribe to ticker for BTC/USD
  ws.send(JSON.stringify({
    event: 'subscribe',
    pair: ['XBT/USD'],
    subscription: {
      name: 'ticker'
    }
  }));
});

ws.on('message', (data) => {
  const message = JSON.parse(data);
  
  // Ticker format: [channelID, tickerData, pair, channelName]
  if (Array.isArray(message) && message[2] === 'XBT/USD') {
    const [channelID, ticker, pair, channelName] = message;
    console.log(`BTC Price: Bid ${ticker.b[0]}, Ask ${ticker.a[0]}`);
  }
});

// Heartbeat every 30 seconds
setInterval(() => {
  ws.send(JSON.stringify({ event: 'ping' }));
}, 30000);

As assinaturas WebSocket retornam dados em formato de array com IDs de canal numéricos. Mapeie esses IDs para suas assinaturas para rotear os dados corretamente.

Streaming de Livro de Ordens

Assine os dados do livro de ordens de Nível 2:

ws.send(JSON.stringify({
  event: 'subscribe',
  pair: ['XBT/USD'],
  subscription: {
    name: 'book',
    depth: 25  // 25, 100, 500, or 1000 levels
  }
}));

O feed do livro envia snapshots seguidos por atualizações incrementais. Mantenha o estado do livro de ordens local aplicando os deltas:

let orderBook = { asks: {}, bids: {} };

ws.on('message', (data) => {
  const message = JSON.parse(data);
  
  if (message[1] === 'as' || message[1] === 'bs') {
    // Snapshot: initialize order book
    const [channelID, type, asks, bids] = message;
    orderBook.asks = Object.fromEntries(asks.map(([price, volume]) => [price, volume]));
    orderBook.bids = Object.fromEntries(bids.map(([price, volume]) => [price, volume]));
  } else if (message[1] === 'a' || message[1] === 'b') {
    // Update: apply delta
    const [channelID, type, delta] = message;
    const side = type === 'a' ? 'asks' : 'bids';
    
    delta.forEach(([price, volume]) => {
      if (volume === '0.00000000') {
        delete orderBook[side][price];
      } else {
        orderBook[side][price] = volume;
      }
    });
  }
});

Autenticação de WebSocket Privado

Obtenha um token WebSocket via REST:

token_response = kraken.private_request('GetWebSocketsToken')
token = token_response['result']['token']

Conecte-se ao WebSocket privado:

const privateWs = new WebSocket('wss://ws-auth.kraken.com');

privateWs.on('open', () => {
  // Authenticate
  privateWs.send(JSON.stringify({
    event: 'subscribe',
    subscription: {
      name: 'ownTrades',
      token: 'YOUR_WEBSOCKET_TOKEN'
    }
  }));
});

privateWs.on('message', (data) => {
  const message = JSON.parse(data);
  
  if (message[1] === 'ownTrades') {
    console.log('Your trade executed:', message[0]);
  }
});

Os tokens WebSocket privados expiram após 15 minutos. Implemente a lógica automática de atualização de token e reconexão para sistemas de produção.

Negociação de Futuros e Recursos Avançados

A Kraken Futures oferece infraestrutura separada para negociação de derivativos com tipos de ordem avançados e margem de portfólio.

Autenticação de Futuros

Os Futuros usam autenticação por token Bearer distinta do HMAC Spot:

import requests
import hmac
import hashlib
import base64
import json

class KrakenFuturesAuth:
    def __init__(self, api_key, api_secret):
        self.api_key = api_key
        self.api_secret = api_secret
        self.base_url = "https://futures.kraken.com/api/v3"
    
    def generate_signature(self, endpoint, method, body=None):
        nonce = str(int(time.time() * 1000))
        message = endpoint + method + nonce
        
        if body:
            message += json.dumps(body, separators=(',', ':'))
        
        signature = base64.b64encode(
            hmac.new(
                base64.b64decode(self.api_secret),
                message.encode(),
                hashlib.sha256
            ).digest()
        ).decode()
        
        return {
            'APIKey': self.api_key,
            'Nonce': nonce,
            'Authent': signature,
            'Content-Type': 'application/json'
        }
    
    def request(self, endpoint, method='GET', body=None):
        url = f"{self.base_url}{endpoint}"
        headers = self.generate_signature(endpoint, method, body)
        
        if method == 'GET':
            response = requests.get(url, headers=headers)
        else:
            response = requests.post(url, headers=headers, json=body)
        
        return response.json()

# Usage
futures = KrakenFuturesAuth('FUTURES_API_KEY', 'FUTURES_SECRET')

Realização de Ordem de Futuros

Faça uma ordem limite no contrato perpétuo de Bitcoin:

order = futures.request('/sendorder', 'POST', {
    'orderType': 'lmt',
    'side': 'buy',
    'size': 1,
    'limitPrice': 65000,
    'symbol': 'PI_XBTUSD'  # Perpetual Inverse BTC/USD
})

Os símbolos de Futuros usam convenções diferentes:

• PI_XBTUSD: Contrato Perpétuo Inverso Bitcoin/USD
• PF_ETHUSD: Contrato Perpétuo Linear Ethereum/USD
• FI_XBTUSD_250228: Futuros de vencimento fixo com expiração em 28 de fevereiro de 2025

Operações em Lote

A API de Futuros suporta o envio de ordens em lote:

batch = futures.request('/batchorder', 'POST', {
    'batchOrder': [
        {
            'order': 'send',
            'order_tag': '1',
            'orderType': 'lmt',
            'symbol': 'PI_XBTUSD',
            'side': 'buy',
            'size': 1,
            'limitPrice': 64000
        },
        {
            'order': 'send',
            'order_tag': '2',
            'orderType': 'lmt',
            'symbol': 'PI_XBTUSD',
            'side': 'sell',
            'size': 1,
            'limitPrice': 66000
        }
    ]
})

Recursos Avançados de Ordem

• Trailing Stops: O preço de stop ajusta-se com o movimento do mercado
• Take Profit / Stop Loss: Ordens bracket para gerenciamento de risco
• Post-Only: Garante que as ordens adicionem liquidez (taxas de maker)
• Reduce-Only: Impede que a posição aumente

Switch do Homem Morto (Dead Man's Switch)

Cancele todas as ordens se a conexão for perdida:

# Set 60-second timeout
kraken.private_request('CancelAllOrdersAfter', {
    'timeout': 60
})

Isso cria um temporizador no lado do servidor — se você não enviar um heartbeat dentro de 60 segundos, a Kraken cancelará automaticamente todas as ordens abertas.

Conclusão

A API da Kraken oferece acesso de nível institucional aos mercados de criptomoedas por meio de interfaces REST, WebSocket e Futuros dedicadas. Você autentica com assinaturas HMAC-SHA512, gerencia sequências de nonce cuidadosamente e escala de negociação à vista para futuros alavancados. Os limites de taxa em camadas acomodam estratégias desde o reequilíbrio casual de portfólio até a criação de mercado de alta frequência.

Comece com o ambiente de sandbox para testar a autenticação e a realização de ordens. Use chaves de API separadas para cada estratégia de negociação para evitar conflitos de nonce. Implemente conexões WebSocket para dados em tempo real e switches do homem morto (dead man's switches) para gerenciamento de risco. Monitore os cabeçalhos de limite de taxa e implemente um backoff exponencial para erros 429.

Ao construir aplicações de negociação de cripto — seja testando endpoints da Kraken, depurando assinaturas de autenticação ou gerenciando múltiplas integrações de API — otimize seu fluxo de trabalho de desenvolvimento com o Apidog. Ele lida com testes visuais de API, geração automatizada de documentação e colaboração em equipe para que você possa focar na lógica de negociação em vez de se debater com assinaturas HMAC.