OKX API: Guia Completo da Documentação para Criptomoedas

作者

OKX API: Guia Completo da Documentação para Criptomoedas

Se você está começando no universo das criptomoedas ou já tem alguma experiência e deseja automatizar suas estratégias, entender a documentação da API da OKX é fundamental. Neste artigo, vamos analisar cada detalhe técnico, mostrar como configurar a autenticação, explorar os principais endpoints e apresentar boas práticas de segurança. Tudo isso pensado para o público brasileiro, com exemplos em português e referências a preços em reais quando necessário.

Principais Pontos

  • Visão geral da OKX e sua plataforma de negociação.
  • Tipos de APIs disponíveis: REST, WebSocket e FIX.
  • Processo de criação de API Key e configuração de permissões.
  • Endpoints essenciais para mercado, conta e trading.
  • Limites de taxa (rate limits) e como evitá‑los.
  • Segurança: assinatura HMAC‑SHA256, IP whitelist e boas práticas.
  • Exemplos práticos em Python e Node.js.
  • Ambiente sandbox para testes sem risco.

O que é a OKX?

A OKX é uma das maiores exchanges de cripto do mundo, oferecendo negociação de spot, futures, options e perpetual swaps. No Brasil, a plataforma ganhou destaque por sua interface intuitiva, baixa latência e suporte a múltiplas moedas fiduciárias, como o real (R$). Para desenvolvedores, a OKX disponibiliza uma documentação de API robusta que permite integrar bots de trading, dashboards personalizados e aplicativos de gerenciamento de carteira.

Visão geral da API da OKX

A API da OKX está dividida em três camadas principais:

1. API REST

Usada para chamadas síncronas, como obter cotações, histórico de ordens e executar trades. As requisições são feitas via HTTPS e retornam JSON.

2. WebSocket

Ideal para receber dados em tempo real, como fluxo de cotações (ticker), livro de ofertas (order book) e atualizações de ordens. A conexão permanece aberta, reduzindo a latência.

3. FIX Protocol

Para traders institucionais que precisam de alta performance e confiabilidade, a OKX oferece acesso via FIX, mas este guia focará nas APIs REST e WebSocket, que são as mais usadas por desenvolvedores individuais.

Como criar e configurar sua API Key

Antes de qualquer chamada, é necessário gerar uma API Key na sua conta OKX. Siga os passos:

  1. Acesse okx.com e faça login.
  2. Vá em Account > API no menu superior.
  3. Clique em Create API Key e escolha um nome descritivo.
  4. Selecione as permissões necessárias:
    • Read‑only – apenas consulta de dados (ideal para dashboards).
    • Trade – permite enviar ordens.
    • Withdrawal – não recomendado para a maioria dos usuários.
  5. Configure a IP whitelist inserindo os endereços IP que poderão usar a chave. Isso reduz o risco de uso indevido.
  6. Salve a chave e anote o API Key, Secret Key e Passphrase. Guarde‑os em um cofre seguro (ex.: 1Password).

⚠️ Importante: Nunca exponha sua Secret Key em repositórios públicos. Use variáveis de ambiente no seu código.

Autenticação: assinatura HMAC‑SHA256

Para chamadas que requerem autenticação (ex.: criar ordem, obter saldo), a OKX exige que você envie um cabeçalho OK-ACCESS-SIGN gerado da seguinte forma:

signature = base64( HMAC_SHA256( secret_key, timestamp + method + request_path + body ) )

Onde:

  • timestamp – UTC no formato ISO8601, ex.: 2025-11-20T12:34:56.789Z.
  • method – verbo HTTP (GET, POST, DELETE).
  • request_path – caminho da URL sem domínio, incluindo query string.
  • body – string JSON vazia para GET, ou o payload para POST.

O cabeçalho completo inclui ainda:

  • OK-ACCESS-KEY – sua API Key.
  • OK-ACCESS-PASSPHRASE – a passphrase definida ao criar a chave.
  • OK-ACCESS-TIMESTAMP – o mesmo timestamp usado na assinatura.

Exemplo em Python (biblioteca requests):

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

API_KEY = "sua_api_key"
SECRET_KEY = "sua_secret_key"
PASSPHRASE = "sua_passphrase"
BASE_URL = "https://www.okx.com"

timestamp = time.strftime('%Y-%m-%dT%H:%M:%S.%fZ', time.gmtime())
method = "POST"
request_path = "/api/v5/trade/order"
body = json.dumps({"instId":"BTC-USDT","tdMode":"cash","side":"buy","ordType":"market","sz":"0.001"})
message = timestamp + method + request_path + body
signature = base64.b64encode(hmac.new(SECRET_KEY.encode(), message.encode(), hashlib.sha256).digest())

headers = {
    "OK-ACCESS-KEY": API_KEY,
    "OK-ACCESS-SIGN": signature.decode(),
    "OK-ACCESS-TIMESTAMP": timestamp,
    "OK-ACCESS-PASSPHRASE": PASSPHRASE,
    "Content-Type": "application/json"
}

response = requests.post(BASE_URL + request_path, headers=headers, data=body)
print(response.json())

Endpoints principais da API REST

A seguir, listamos os grupos de endpoints mais usados, com exemplos de parâmetros e respostas.

1. Dados de Mercado

  • GET /api/v5/market/tickers – retorna preços de todos os pares.
  • GET /api/v5/market/books – obtém o livro de ofertas de um par específico (ex.: instId=BTC-USDT).
  • GET /api/v5/public/instruments – lista os instrumentos disponíveis (spot, futures, options).

Exemplo de chamada para ticker BTC/USDT:

curl -X GET "https://www.okx.com/api/v5/market/ticker?instId=BTC-USDT"

2. Conta e Saldo

  • GET /api/v5/account/balance – consulta saldo por moeda.
  • GET /api/v5/account/positions – posições em contratos futuros.

Exemplo de resposta (em JSON):

{
  "code":"0",
  "data":[
    {"ccy":"BTC","bal":"0.1234","availBal":"0.1234"},
    {"ccy":"USDT","bal":"1500.00","availBal":"1500.00"}
  ]
}

3. Trading (Ordens)

  • POST /api/v5/trade/order – cria ordem (market, limit, stop).
  • GET /api/v5/trade/orders-pending – lista ordens pendentes.
  • POST /api/v5/trade/cancel-order – cancela ordem.

Exemplo de ordem limit:

{
  "instId":"BTC-USDT",
  "tdMode":"cash",
  "side":"sell",
  "ordType":"limit",
  "px":"65000",
  "sz":"0.005"
}

4. WebSocket – Streams em Tempo Real

Para receber dados de ticker e livro de ofertas sem sobrecarregar a API REST, use o endpoint WebSocket:

wss://ws.okx.com:8443/ws/v5/public

Após conectar, envie a mensagem de assinatura:

{
  "op": "subscribe",
  "args": [{"channel": "tickers", "instId": "BTC-USDT"}]
}

O servidor retornará atualizações como:

{
  "channel": "tickers",
  "data": [{"instId":"BTC-USDT","last":"65234.5","bidPx":"65230","askPx":"65240"}]
}

Limites de taxa (Rate Limits) e como lidar com eles

A OKX impõe limites por minuto para cada endpoint. Exemplo típico:

  • GET /api/v5/market/tickers – 30 chamadas por segundo.
  • POST /api/v5/trade/order – 10 chamadas por segundo.

Se exceder o limite, a API retornará o código 429 com mensagem “Rate limit exceeded”. Estratégias recomendadas:

  1. Implementar exponential backoff ao receber 429.
  2. Usar caching local para dados que não mudam a cada segundo (ex.: lista de instrumentos).
  3. Distribuir chamadas entre múltiplas chaves (respeitando a política de uso).

Segurança avançada

Além da assinatura HMAC, adote as boas práticas abaixo:

  • IP Whitelist: limite o acesso à API apenas aos servidores que realmente executam seu código.
  • Rotação de chaves: troque a API Key a cada 90 dias ou ao detectar comportamento suspeito.
  • Logs de auditoria: registre cada chamada (timestamp, endpoint, payload) em um storage seguro para auditoria.
  • HTTPS obrigatório: nunca faça chamadas sem TLS.

Exemplos de código prático

Python – Consultando o ticker e executando ordem de compra

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

API_KEY = "SUA_API_KEY"
SECRET_KEY = "SUA_SECRET_KEY"
PASSPHRASE = "SUA_PASSPHRASE"
BASE_URL = "https://www.okx.com"

def sign(timestamp, method, request_path, body=""):
    message = timestamp + method + request_path + body
    mac = hmac.new(SECRET_KEY.encode(), message.encode(), hashlib.sha256)
    return base64.b64encode(mac.digest()).decode()

# 1. Obter ticker BTC/USDT
resp = requests.get(f"{BASE_URL}/api/v5/market/ticker?instId=BTC-USDT")
print("Ticker:", resp.json())

# 2. Criar ordem market de compra de 0.001 BTC
timestamp = time.strftime('%Y-%m-%dT%H:%M:%S.%fZ', time.gmtime())
method = "POST"
path = "/api/v5/trade/order"
body = json.dumps({
    "instId": "BTC-USDT",
    "tdMode": "cash",
    "side": "buy",
    "ordType": "market",
    "sz": "0.001"
})
signature = sign(timestamp, method, path, body)
headers = {
    "OK-ACCESS-KEY": API_KEY,
    "OK-ACCESS-SIGN": signature,
    "OK-ACCESS-TIMESTAMP": timestamp,
    "OK-ACCESS-PASSPHRASE": PASSPHRASE,
    "Content-Type": "application/json"
}
order_resp = requests.post(BASE_URL + path, headers=headers, data=body)
print("Ordem:", order_resp.json())

Node.js – Subscrição ao WebSocket de ticker

const WebSocket = require('ws');
const ws = new WebSocket('wss://ws.okx.com:8443/ws/v5/public');

ws.on('open', () => {
  const subMsg = {
    op: 'subscribe',
    args: [{ channel: 'tickers', instId: 'BTC-USDT' }]
  };
  ws.send(JSON.stringify(subMsg));
});

ws.on('message', data => {
  const msg = JSON.parse(data);
  if (msg.channel === 'tickers') {
    console.log('Preço BTC/USDT:', msg.data[0].last);
  }
});

Ambiente Sandbox – Teste sem risco

A OKX oferece um sandbox gratuito que replica a produção, mas com fundos fictícios. Use o endpoint base https://www.okx.com para produção e https://www.okx.com (substitua por https://www.okx.com conforme a documentação) para sandbox. O processo de criação de chave é o mesmo, porém os limites de taxa são mais generosos, permitindo testes intensivos.

Boas práticas para desenvolvedores brasileiros

  • Localização de horário: a API espera timestamps em UTC. Converta sempre usando datetime.utcnow() ou time.gmtime().
  • Conversão de moedas: ao exibir valores ao usuário, converta de USDT para real (R$) usando a cotação do dia, por exemplo via API da BRAPI.
  • Tratamento de erros: a OKX devolve códigos de erro padronizados (ex.: 400, 401, 500). Mapeie-os para mensagens claras no seu UI.
  • Documentação atualizada: a OKX atualiza sua API periodicamente. Inscreva‑se no newsletter de desenvolvedores e monitore o changelog.

FAQ – Perguntas Frequentes

1. Posso usar a mesma API Key em vários projetos?

Sim, mas não é recomendado. Cada chave tem permissões específicas; separar chaves por projeto facilita revogar acesso caso um dos ambientes seja comprometido.

2. Qual a diferença entre instId e ccy?

instId representa o par de negociação (ex.: BTC-USDT), enquanto ccy indica a moeda isolada (ex.: BTC ou USDT) usada em endpoints de saldo.

3. Como lidar com limites de taxa ao usar múltiplas contas?

Cada conta possui seus próprios limites. Se precisar de alta frequência, distribua a carga entre contas diferentes, mas respeite a política de uso justo da OKX.

4. A API suporta WebSocket com autenticação?

Sim. Para canais privados (ex.: ordens, posições), envie um login com assinatura HMAC similar à REST antes de subscrever.

Conclusão

A documentação da OKX API oferece tudo que desenvolvedores brasileiros precisam para criar bots, dashboards e integrações de trading avançadas. Ao seguir as etapas de criação de chave, implementar corretamente a assinatura HMAC‑SHA256, respeitar os limites de taxa e adotar boas práticas de segurança, você garante um ambiente estável e protegido. Use o sandbox para validar seu código antes de operar com fundos reais e, sempre que possível, aproveite as bibliotecas de código aberto da comunidade para acelerar o desenvolvimento.

Com este guia completo, você está pronto para explorar todo o potencial da OKX e levar suas estratégias de criptomoedas ao próximo nível.