Documentação da API

Visão Geral

A API da ExBull permite consultar saldo, payout de ativos e criar ordens de negociação de forma programática. Ela foi feita para bots e scripts externos — tudo que você vê aqui pode ser usado por uma IA ou por um desenvolvedor júnior sem precisar olhar o código-fonte do servidor.

Autenticação

Gere uma chave em /account/api-keys (aba "API" do painel). Você recebe um par apiKey / apiSecret — o secret só aparece uma vez, na criação. Se perder, revogue a chave e gere outra. Nunca compartilhe ou versione o secret em repositórios públicos.

Envie os dois em todas as requisições autenticadas, como headers HTTP:

X-Api-Key: ak_live_xxx
X-Api-Secret: sk_live_xxx

Cada chave tem um ou mais escopos, que definem o que ela pode fazer:

Se a autenticação falhar ou o escopo for insuficiente, a API responde:

Rate Limiting

Existem dois limitadores independentes: um para rotas de leitura (readLimiter) e outro, mais restritivo, para criação de ordens (tradeLimiter). Ao estourar o limite, a API responde 429. Seu bot deve tratar esse status com backoff (espere e tente de novo, não em loop imediato) — nunca assuma que 429 significa erro de negócio.

Formato de Resposta

Toda resposta é um JSON com um campo success booleano:

// sucesso
{ "success": true, ... }

// erro
{ "success": false, "error": "mensagem legível do que deu errado" }

Regra prática para bots: sempre cheque success primeiro. Se for false, trate error como texto para log/alerta, não tente parsear ele para decidir lógica de negócio.

Como Funciona a Criação de Ordens (Importante)

POST /orders é assíncrono. Ele não cria a ordem na hora — ele enfileira um job e responde imediatamente com 202 e um jobId. Isso existe porque a criação real da ordem envolve outra camada interna (fila + worker), então seu bot precisa consultar o resultado depois, não assumir que a ordem já existe.

Estados possíveis de status no polling: waiting, active, delayed (ainda processando — continue tentando), completed (deu certo — veio a ordem criada) ou failed (rejeitada por regra de negócio — pare de tentar, o erro está em error).

Endpoints

{ "success": true, "timestamp": 1735689600000 }

{ "success": true, "accountType": "demo", "balance": 985.32 }

{ "success": true, "stats": { ... } }

{
  "success": true,
  "payout": [
    { "symbol": "EURUSD", "payoutPercentage": 87 },
    { "symbol": "GBPUSD", "payoutPercentage": 82 }
  ]
}

{ "success": true, "payout": { "symbol": "EURUSD", "payoutPercentage": 87 } }

{
  "symbol": "EURUSD",
  "direction": "up",
  "amount": 10,
  "expirationSeconds": 60
}

{
  "success": true,
  "status": "queued",
  "jobId": "12345",
  "statusUrl": "/api/v1/orders/status/12345"
}

// ainda processando
{ "success": true, "status": "active" }

// concluído
{ "success": true, "status": "completed", "order": { "id": "...", "status": "active", "expires_at": "...", ... } }

// rejeitado
{ "success": false, "status": "failed", "error": "motivo da rejeição" }

{ "success": true, "orders": [ { "id": "...", "symbol": "EURUSD", "status": "active", ... } ] }

GET /orders/history?startDate=2026-06-01&endDate=2026-06-30

{ "success": true, "order": { "id": "...", "status": "won", "exit_price": 1.0842, "profit": 8.7, ... } }

Referência Rápida

Exemplo Completo (Node.js)

Fluxo mínimo para um bot: checar payout, abrir ordem e aguardar o resultado. Requer Node 18+ (usa fetch nativo, sem dependências).

const BASE_URL = 'https://ex-bull.com/api/v1';
const headers = {
  'Content-Type': 'application/json',
  'X-Api-Key': process.env.API_KEY,
  'X-Api-Secret': process.env.API_SECRET,
};

async function criarOrdem(symbol, direction, amount, expirationSeconds) {
  // 1. Confirma que o ativo está disponível antes de tentar operar
  const payoutRes = await fetch(`${BASE_URL}/payout/${symbol}`, { headers });
  const payoutData = await payoutRes.json();
  if (!payoutData.success) throw new Error(`Ativo indisponível: ${payoutData.error}`);

  // 2. Enfileira a ordem
  const orderRes = await fetch(`${BASE_URL}/orders`, {
    method: 'POST',
    headers,
    body: JSON.stringify({ symbol, direction, amount, expirationSeconds }),
  });
  const orderData = await orderRes.json();
  if (orderRes.status !== 202) throw new Error(`Falha ao enfileirar: ${orderData.error}`);

  // 3. Faz polling até sair de waiting/active/delayed
  const deadline = Date.now() + 20_000;
  while (Date.now() < deadline) {
    const statusRes = await fetch(`${BASE_URL}/orders/status/${orderData.jobId}`, { headers });
    const statusData = await statusRes.json();

    if (statusData.status === 'completed') return statusData.order;
    if (statusData.status === 'failed') throw new Error(`Ordem rejeitada: ${statusData.error}`);

    await new Promise((r) => setTimeout(r, 500));
  }
  throw new Error('Timeout aguardando confirmação da ordem');
}

Checklist de Boas Práticas para Bots

• Sempre confira success antes de ler qualquer outro campo da resposta.
• Trate POST /orders como assíncrono — nunca assuma que a ordem existe só porque veio 202.
• Defina um timeout de polling e não reenvie o mesmo POST /orders automaticamente ao estourar — isso pode duplicar ordens.
• Trate 429 com espera/backoff, nunca com retry imediato em loop.
• Guarde apiSecret em variável de ambiente, nunca em código versionado.
• Use uma chave com escopo read para qualquer bot que só consulta dados — reserve o escopo trade só para o que realmente opera.