API per sviluppatori

Invia la tua chiave fom_live_… come token Bearer: /api/v1/meta ne conferma la validità, /api/v1/screener restituisce lo screener ordinato per punteggio in formato JSON, con header sui limiti di richieste in ogni risposta.

La Formion Data API offre accesso programmatico agli stessi segnali che vedi nell’app — lo screener ordinato per punteggio, le probabilità di successo calibrate e altro — tramite un semplice endpoint REST autenticato. È pensata per analisti quantitativi, sviluppatori di bot e desk di trading che vogliono integrare il vantaggio operativo di Formion nei propri sistemi.

Stato: disponibile su richiesta. Le chiavi vengono emesse manualmente dal team Formion. I token API personali self-service sono in programma — la scheda di accesso API in Profilo → Licenza mostra In arrivo. Contatta [email protected] per richiedere una chiave.

Autenticazione

Ogni richiesta include la tua chiave API come token bearer:

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

Le chiavi hanno il formato fom_live_…. Trattale come una password — chiunque possieda la chiave può chiamare l’API a tuo nome.
La chiave viene mostrata una sola volta al momento dell’emissione e conservata sui nostri sistemi solo come hash. Se la perdi, la revochiamo e ne emettiamo una nuova — non possiamo recuperarla.
Puoi anche passare la chiave come ?api_key=… per test rapidi, ma è preferibile usare l’header Authorization.

Se la chiave è assente, errata o revocata, ricevi:

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

con HTTP 401.

Limiti di richieste

Ogni chiave ha un limite al minuto definito dal suo livello API (assegnato al momento dell’emissione):

Livello	Richieste / minuto
Free	60
Pro	600
Institutional	6 000

Ogni risposta include header standard per regolare autonomamente la frequenza delle richieste:

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

Il superamento del limite restituisce HTTP 429 con { "ok": false, "error": "rate_limited", "tier": "…" } e un header Retry-After (secondi). Attendi prima di riprovare.

Versionamento

Tutti gli endpoint si trovano sotto /api/v1/. Consideriamo la struttura delle risposte v1 un contratto stabile — possono essere aggiunti nuovi campi, ma quelli esistenti non cambieranno significato né scompariranno senza una nuova versione (/api/v2/). Puoi sviluppare su v1 con fiducia.

Endpoint

GET /api/v1/meta`

Conferma che la chiave funzioni ed elenca gli endpoint a cui può accedere.

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`

Lo screener multimercato ordinato per punteggio — lo stesso motore che alimenta la scheda Screener dell’app.

Parametri di query

Parametro	Predefinito	Descrizione
`tf`	`1d`	Timeframe: `5m`, `15m`, `1h`, `4h`, `1d`
`limit`	`100`	Righe da restituire (max 500)
`minScore`	`0`	Restituisce solo le righe con punteggio ≥ questo valore

Esempio

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

Riferimento dei campi

Campo	Significato
`symbol`	Coppia sull’exchange o ticker
`asset_class`	Classe di attività della riga (ad esempio `crypto`, `stock`, `index`, `commodity`)
`category`	Classe del setup (`bull`, `bear-rally`, `sweep-confirmed`, …)
`direction`	`long`, `short` o `null`
`score`	Punteggio composito Formion, 0–100
`win_probability`	Probabilità calibrata dal modello che il segnale sia corretto sull’orizzonte del timeframe, oppure `null` se il modello non ha superato la soglia di accuratezza richiesta
`rsi_1d`	RSI(14) giornaliero
`tags`	Tag strutturali + di momentum (FVG, BoS/CHoCH, VWAP, inversioni dell’Adaptive-RSI, …)
`scanned_at`	Timestamp Unix in ms della scansione sottostante (i dati possono risalire a qualche minuto prima)

Questi due endpoint (/meta e /screener) costituiscono oggi l’intera API v1. Se ti servono altri dati, dicci quali — al momento non è previsto alcun impegno ad aggiungere altri endpoint.

Buone pratiche

Usa la cache e interroga l’API con criterio. Lo screener esegue una nuova scansione ogni pochi minuti; interrogarlo più spesso consuma il limite di richieste per ottenere dati identici. Leggi scanned_at e salta la richiesta se non è cambiato.
Una chiave per sistema. Non condividere una chiave tra client — la misurazione per chiave permette a noi (e a te) di monitorare l’utilizzo.
Non includere mai una chiave nel codice destinato al browser o in un repository pubblico. Se una chiave viene esposta, scrivici via email per consentirci di revocarla ed emetterne una nuova.

Ottenere una chiave

Scrivi a [email protected] indicando il tuo caso d’uso e il volume previsto. Emetteremo una chiave, imposteremo il suo livello e ti aiuteremo a far funzionare la prima chiamata.