Futura Broker API

API REST somente-leitura para consultar saldo e histórico de operações da sua conta.

A Futura Broker API é uma API REST somente-leitura. Com uma chave de API você consulta o saldo e o histórico de operações fechadas da sua conta — ideal para planilhas, dashboards pessoais e relatórios.

As chaves têm permissão exclusivamente de leitura. Não é possível abrir operações, sacar ou transferir pela API. Ainda assim, trate sua chave como uma senha: quem tiver o token consegue ler os dados financeiros da sua conta.

Base URL

https://api.futurabroker.com/api/public/v1

Autenticação

Toda requisição precisa do header Authorization com sua chave no formato Bearer:

Authorization: Bearer fb_live_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Gere sua chave direto na plataforma, em Configurações → Integrações (futurabroker.com/settings?tab=integrations). O token completo é exibido uma única vez no momento da criação — guarde-o com segurança. Se perder, basta revogar a chave antiga e gerar outra na mesma tela. Você pode manter até 10 chaves ativas ao mesmo tempo.

Limites de uso

60 requisições por minuto por chave. Ao exceder, a API responde 429 com o header Retry-After.
Os headers X-RateLimit-Limit e X-RateLimit-Remaining acompanham cada resposta.

Formato das respostas

Toda resposta segue o envelope padrão:

{
  "success": true,
  "data": { },
  "meta": { "timestamp": "...", "requestId": "..." }
}

Em caso de erro, success é false e error traz code e message.

Endpoints

`GET /ping`

Testa a conectividade e a validade da sua chave.

{
  "success": true,
  "data": {
    "pong": true,
    "key_prefix": "a6240e5c7b",
    "scopes": ["read"],
    "server_time": "2026-07-19T06:17:18.476Z"
  }
}

`GET /account/balance`

Retorna os saldos da conta.

Campo	Tipo	Descrição
`balance`	number	Saldo real
`balance_bonus`	number	Saldo de bônus/afiliado
`balance_demo`	number	Saldo da conta demo
`currency`	string	Moeda (ex.: `BRL`)

{
  "success": true,
  "data": {
    "balance": 1109.13,
    "balance_bonus": 0,
    "balance_demo": 25830.67,
    "currency": "BRL"
  }
}

`GET /trades`

Histórico de operações fechadas (resultado win, lose ou draw), ordenado da mais recente para a mais antiga.

Parâmetros de query (todos opcionais):

Parâmetro	Tipo	Descrição
`limit`	number	Itens por página (1–100, padrão 50)
`cursor`	number	ID da operação para paginar (use o `next_cursor` da resposta anterior)
`from`	ISO 8601	Data/hora inicial (ex.: `2026-07-01T00:00:00Z`)
`to`	ISO 8601	Data/hora final
`asset`	string	Filtra por ativo (ex.: `ETHUSDT`)
`result`	string	`win`, `lose` ou `draw`
`demo`	string	`true` ou `false`

Campos de cada operação:

Campo	Tipo	Descrição
`id`	number	Identificador da operação
`asset`	string	Ativo negociado
`direction`	string	`buy` (alta) ou `sell` (baixa)
`amount`	number	Valor investido
`entry_price`	number	Preço de entrada
`exit_price`	number \| null	Preço de saída
`payout_percent`	number	Payout aplicado (%)
`profit`	number \| null	Lucro (positivo) ou prejuízo (negativo)
`result`	string	`win`, `lose` ou `draw`
`demo`	boolean	Se foi operação demo
`opened_at`	ISO 8601	Abertura
`closed_at`	ISO 8601	Fechamento

{
  "success": true,
  "data": {
    "trades": [
      {
        "id": 2703209,
        "asset": "ETHUSDT",
        "direction": "sell",
        "amount": 10,
        "entry_price": 1873.59,
        "exit_price": 1873.7,
        "payout_percent": 80,
        "profit": -10,
        "result": "lose",
        "demo": false,
        "opened_at": "2026-06-03T06:40:07.000Z",
        "closed_at": "2026-06-03T06:41:00.000Z"
      }
    ],
    "next_cursor": 2703206
  }
}

Paginação: quando houver mais resultados, next_cursor traz o ID para a próxima página. Repita a chamada passando cursor=<next_cursor> até que next_cursor venha null.

Sincronizando com frequência? Use from=. Em vez de repaginar o histórico inteiro a cada execução, guarde a data da operação mais recente que você já tem e busque só o que é novo com ?from=<última data>. Uma sincronização típica cai de dezenas de requisições para uma — mais rápida pra você e sem risco de esbarrar no limite de 60 req/min. O exemplo abaixo já faz isso.

Exemplo: Google Sheets (sincronização incremental)

Cole o script abaixo em Extensões → Apps Script na sua planilha, troque o token e rode sincronizarOperacoes. A primeira execução importa o histórico completo; as seguintes buscam apenas as operações novas e as acrescentam ao fim da aba. Agende um acionador (Apps Script → Acionadores) para rodar de tempos em tempos.

const API_BASE = 'https://api.futurabroker.com/api/public/v1'
const API_KEY = 'fb_live_xxxxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

// Busca com backoff automático: se bater no limite (429), espera o
// Retry-After e repete a MESMA página — assim um histórico grande sincroniza
// inteiro sem quebrar, só mais devagar.
function buscarComRetry(url, headers) {
  for (let tentativa = 0; tentativa < 6; tentativa++) {
    const resp = UrlFetchApp.fetch(url, { headers: headers, muteHttpExceptions: true })
    if (resp.getResponseCode() === 429) {
      const h = resp.getHeaders()
      const espera = Number(h['Retry-After'] || h['retry-after'] || 60)
      Utilities.sleep((espera + 1) * 1000)
      continue
    }
    return JSON.parse(resp.getContentText())
  }
  throw new Error('Limite de requisições persistente — tente novamente mais tarde')
}

function sincronizarOperacoes() {
  const props = PropertiesService.getScriptProperties()
  // Estado da última sincronização: data da operação mais recente + seu ID
  // (o ID evita duplicar a operação que fica exatamente na borda do from=).
  const ultimaData = props.getProperty('ultima_data')
  const ultimoId = Number(props.getProperty('ultimo_id') || 0)
  const headers = { Authorization: 'Bearer ' + API_KEY }
  const aba = SpreadsheetApp.getActiveSheet()

  if (aba.getLastRow() === 0) {
    aba.appendRow(['Data', 'Ativo', 'Direção', 'Valor', 'Entrada', 'Saída', 'Resultado', 'Lucro'])
  }

  const novas = []
  let maiorId = ultimoId
  let dataMaisRecente = ultimaData
  let cursor = null
  do {
    let url = API_BASE + '/trades?limit=100'
    if (ultimaData) url += '&from=' + encodeURIComponent(ultimaData)
    if (cursor) url += '&cursor=' + cursor

    const body = buscarComRetry(url, headers)
    if (!body.success) throw new Error(body.error.message)

    body.data.trades.forEach(function (t) {
      if (t.id <= ultimoId) return // já sincronizada numa execução anterior
      novas.push([
        t.closed_at, t.asset, t.direction, t.amount,
        t.entry_price, t.exit_price, t.result, t.profit,
      ])
      if (t.id > maiorId) maiorId = t.id
      if (!dataMaisRecente || t.opened_at > dataMaisRecente) dataMaisRecente = t.opened_at
    })
    cursor = body.data.next_cursor
  } while (cursor)

  if (novas.length > 0) {
    // As operações chegam da mais recente pra mais antiga; inverte pra
    // manter a aba em ordem cronológica.
    novas.reverse()
    aba.getRange(aba.getLastRow() + 1, 1, novas.length, novas[0].length).setValues(novas)
    props.setProperty('ultima_data', dataMaisRecente)
    props.setProperty('ultimo_id', String(maiorId))
  }
}

Códigos de erro

HTTP	`code`	Significado
401	`UNAUTHORIZED`	Header `Authorization` ausente ou malformado
401	`INVALID_API_KEY`	Chave inválida ou revogada
403	`FORBIDDEN_SCOPE`	A chave não tem o escopo `read`
400	`VALIDATION_ERROR`	Parâmetro de query inválido
429	`RATE_LIMITED`	Limite de requisições excedido

Nesta página