API para desenvolvedores

Envie sua chave fom_live_… como token Bearer: /api/v1/meta confirma sua validade, /api/v1/screener retorna o screener classificado em JSON, com cabeçalhos de limite de requisições em todas as respostas.

A API de dados Formion oferece acesso programático aos mesmos sinais que você vê no app — o screener classificado, probabilidades de acerto calibradas e muito mais — por meio de um endpoint REST simples e autenticado. Foi projetada para quants, desenvolvedores de bots e mesas de operações que querem a vantagem da Formion em seus próprios sistemas.

Status: disponível mediante solicitação. As chaves são emitidas manualmente pela equipe Formion. Tokens pessoais de API por autoatendimento estão no roadmap — o cartão de acesso à API em Perfil → Licença mostra Em breve. Entre em contato com [email protected] para solicitar uma chave.

Autenticação

Cada requisição inclui sua chave de API como token bearer:

curl "https://app.formion.ai/api/v1/screener?tf=1d&limit=25" \
  -H "Authorization: Bearer fom_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

As chaves têm o formato fom_live_…. Trate-as como uma senha — qualquer pessoa com a chave pode chamar a API em seu nome.
A chave é exibida uma única vez ao ser emitida e armazenada apenas como hash do nosso lado. Se você a perder, revogamos e emitimos outra — não podemos recuperá-la.
Você também pode passar a chave como ?api_key=… para testes rápidos, mas o cabeçalho Authorization é preferível.

Se sua chave estiver ausente, incorreta ou revogada, você receberá:

{ "ok": false, "error": "unauthorized", "hint": "Send a valid key as 'Authorization: Bearer fom_live_…'. Request access at [email protected]." }

com HTTP 401.

Limites de requisições

Cada chave tem um limite por minuto definido pelo seu nível de API (atribuído quando a chave é emitida):

Nível	Requisições / minuto
Gratuito	60
Pro	600
Institutional	6 000

Todas as respostas incluem cabeçalhos padrão para você controlar o ritmo das requisições:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 594
X-RateLimit-Reset: 1789200000     # unix seconds when the window resets

Exceder o limite retorna HTTP 429 com { "ok": false, "error": "rate_limited", "tier": "…" } e um cabeçalho Retry-After (segundos). Aguarde e tente novamente.

Versionamento

Todos os endpoints ficam sob /api/v1/. Tratamos a estrutura de resposta da v1 como um contrato estável — novos campos podem ser adicionados, mas os campos existentes não mudarão de significado nem desaparecerão sem uma nova versão (/api/v2/). Desenvolva com confiança usando a v1.

Endpoints

GET /api/v1/meta`

Confirma que sua chave funciona e lista os recursos que ela pode acessar.

curl https://app.formion.ai/api/v1/meta -H "Authorization: Bearer fom_live_…"

{
  "ok": true,
  "api_version": "v1",
  "key": { "tier": "pro", "rate_per_min": 600, "label": "Acme backtest bot" },
  "endpoints": [
    { "path": "/api/v1/meta", "method": "GET", "desc": "This key's tier + endpoint list." },
    { "path": "/api/v1/screener", "method": "GET", "desc": "Ranked multi-market screener with Formion score + P(win). Query: tf, limit, minScore." }
  ],
  "docs": "https://docs.formion.ai/api",
  "support": "[email protected]"
}

GET /api/v1/screener`

O screener classificado de múltiplos mercados — o mesmo mecanismo usado na aba Screener do app.

Parâmetros de consulta

Parâmetro	Padrão	Descrição
`tf`	`1d`	Período gráfico: `5m`, `15m`, `1h`, `4h`, `1d`
`limit`	`100`	Linhas a retornar (máx. 500)
`minScore`	`0`	Retornar apenas linhas com pontuação ≥ este valor

Exemplo

curl "https://app.formion.ai/api/v1/screener?tf=4h&limit=5&minScore=60" \
  -H "Authorization: Bearer fom_live_…"

{
  "ok": true,
  "api_version": "v1",
  "tier": "pro",
  "timeframe": "4h",
  "scanned_at": 1789199400000,
  "count": 5,
  "data": [
    {
      "symbol": "SOLUSDT",
      "asset_class": "crypto",
      "category": "bull-pullback",
      "direction": "long",
      "score": 74,
      "win_probability": 0.58,
      "rsi_1d": 61,
      "tags": ["at-bull-fvg", "bos-up-1d", "arsi-turn-up-4h"]
    }
  ]
}

Referência dos campos

Campo	Significado
`symbol`	Par da exchange ou ticker
`asset_class`	Classe de ativo da linha (por exemplo `crypto`, `stock`, `index`, `commodity`)
`category`	Classe do setup (`bull`, `bear-rally`, `sweep-confirmed`, …)
`direction`	`long`, `short` ou `null`
`score`	Pontuação composta da Formion, 0–100
`win_probability`	Probabilidade calibrada pelo modelo de o sinal estar correto no horizonte do período gráfico, ou `null` se o modelo ainda não atingiu o nível mínimo de precisão
`rsi_1d`	RSI(14) diário
`tags`	Tags de estrutura + momentum (FVG, BoS/CHoCH, VWAP, viradas do Adaptive-RSI, …)
`scanned_at`	Horário Unix em ms da varredura de origem (os dados podem ter alguns minutos de atraso)

Esses dois endpoints (/meta e /screener) compõem toda a API v1 atualmente. Se precisar de outros dados, diga quais — ainda não há compromisso com endpoints adicionais.

Boas práticas

Use cache e consulte com bom senso. O screener faz uma nova varredura a cada poucos minutos; consultar com mais frequência só consome sua cota de requisições para obter dados idênticos. Leia scanned_at e ignore se não tiver mudado.
Uma chave por sistema. Não compartilhe uma chave entre clientes — a medição por chave é como nós (e você) acompanhamos o uso.
Nunca exponha uma chave em um navegador ou repositório público. Se uma chave vazar, envie um e-mail para nós para que possamos revogá-la e emitir uma nova.

Como obter uma chave

Envie um e-mail para [email protected] com seu caso de uso e volume esperado. Emitiremos uma chave, definiremos seu nível e ajudaremos você a fazer a primeira chamada funcionar.