API para desarrolladores

Envía tu clave fom_live_… como token Bearer: /api/v1/meta la valida, /api/v1/screener devuelve el screener ordenado como JSON, con cabeceras de límite de solicitudes en cada respuesta.

La API de datos de Formion ofrece acceso programático a las mismas señales que ves en la app — el screener ordenado, las probabilidades de acierto calibradas y más — mediante un sencillo endpoint REST autenticado. Está diseñada para analistas cuantitativos, desarrolladores de bots y mesas de trading que quieren integrar la ventaja de Formion en sus propios sistemas.

Estado: disponible bajo solicitud. El equipo de Formion emite las claves manualmente. Los tokens personales de API autogestionados están previstos — la tarjeta de acceso a la API en Perfil → Licencia muestra Próximamente. Contacta con [email protected] para solicitar una clave.

Autenticación

Cada solicitud incluye tu clave de API como token Bearer:

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

• Las claves tienen el formato fom_live_…. Trátalas como una contraseña — cualquiera que tenga la clave puede llamar a la API en tu nombre.
• La clave se muestra una sola vez al emitirse y, por nuestra parte, solo se almacena como hash. Si la pierdes, la revocamos y emitimos otra — no podemos recuperarla.
• También puedes pasar la clave como ?api_key=… para pruebas rápidas, aunque se recomienda la cabecera Authorization.

Si falta tu clave, es incorrecta o está revocada, recibes:

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

con HTTP 401.

Límites de solicitudes

Cada clave tiene un límite por minuto definido por su nivel de API (asignado al emitir la clave):

Nivel	Solicitudes / minuto
Gratuito	60
Pro	600
Institutional	6 000

Cada respuesta incluye cabeceras estándar para que puedas regular la frecuencia de tus solicitudes:

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

Si superas el límite, se devuelve HTTP 429 con { "ok": false, "error": "rate_limited", "tier": "…" } y una cabecera Retry-After (segundos). Espera y vuelve a intentarlo.

Versionado

Todos los endpoints están bajo /api/v1/. Tratamos la estructura de respuesta de v1 como un contrato estable — se pueden añadir campos nuevos, pero los existentes no cambiarán de significado ni desaparecerán sin una nueva versión (/api/v2/). Desarrolla sobre v1 con confianza.

---

Endpoints

GET /api/v1/meta`

Confirma que tu clave funciona y enumera los recursos a los que permite acceder.

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`

El screener multimercado ordenado — el mismo motor que utiliza la pestaña Screener de la app.

Parámetros de consulta

Parámetro	Valor predeterminado	Descripción
tf	1d	Marco temporal: 5m, 15m, 1h, 4h, 1d
limit	100	Filas que se devolverán (máximo 500)
minScore	0	Devolver solo filas con puntuación ≥ este valor

Ejemplo

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"]
    }
  ]
}

Referencia de campos

Campo	Significado
symbol	Par del exchange o ticker
asset_class	Clase de activo de la fila (por ejemplo crypto, stock, index, commodity)
category	Tipo de setup (bull, bear-rally, sweep-confirmed, …)
direction	long, short o null
score	Puntuación compuesta de Formion, 0–100
win_probability	Probabilidad calibrada del modelo de que la señal sea acertada en el horizonte del marco temporal, o null si el modelo no ha superado su umbral de precisión
rsi_1d	RSI(14) diario
tags	Etiquetas de estructura + momentum (FVG, BoS/CHoCH, VWAP, giros de Adaptive-RSI, …)
scanned_at	Marca de tiempo Unix en ms del escaneo subyacente (los datos pueden tener unos minutos de antigüedad)

Estos dos endpoints (/meta y /screener) constituyen toda la API v1 actual. Si necesitas otros datos, dinos cuáles — aún no hay ningún compromiso de añadir más endpoints.

---

Buenas prácticas

• Usa la caché y consulta con sensatez. El screener vuelve a escanear cada pocos minutos; consultar con más frecuencia solo consume tu cuota de solicitudes para obtener datos idénticos. Lee scanned_at y omite la consulta si no ha cambiado.
• Una clave por sistema. No compartas una clave entre clientes — la medición por clave nos permite (a nosotros y a ti) evaluar el uso.
• Nunca incluyas una clave en un navegador o repositorio público. Si se filtra una clave, escríbenos por correo para que podamos revocarla y emitir una nueva.

Obtener una clave

Escribe a [email protected] con tu caso de uso y el volumen previsto. Emitiremos una clave, configuraremos su nivel y te ayudaremos a realizar la primera llamada.