API za razvojne programere

Pošaljite svoj ključ fom_live_… kao Bearer token: /api/v1/meta potvrđuje njegovu valjanost, /api/v1/screener vraća rangirani screener kao JSON, uz zaglavlja s ograničenjima broja zahtjeva u svakom odgovoru.

Formion Data API omogućuje programski pristup istim signalima koje vidite u aplikaciji — rangiranom screeneru, kalibriranim vjerojatnostima dobitnog trgovanja i drugim podacima — putem jednostavne REST pristupne točke s autentifikacijom. Namijenjen je kvantitativnim analitičarima, autorima botova i trgovačkim timovima koji žele Formionovu prednost u vlastitim sustavima.

Status: dostupno na zahtjev. Ključeve ručno izdaje tim Formion. Samostalno izdavanje osobnih API tokena u planu je razvoja — kartica za API pristup u Profil → Licenca prikazuje Uskoro. Obratite se na [email protected] kako biste zatražili ključ.

Autentifikacija

Svaki zahtjev sadrži vaš API ključ kao bearer token:

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

• Ključevi izgledaju kao fom_live_…. Čuvajte ih kao lozinku — svatko tko ima ključ može pozivati API u vaše ime.
• Ključ se prikazuje jednom, pri izdavanju, a kod nas se pohranjuje samo kao hash. Ako ga izgubite, opozvat ćemo ga i izdati novi — ne možemo ga obnoviti.
• Za brzo testiranje ključ možete proslijediti i kao ?api_key=…, ali preporučuje se zaglavlje Authorization.

Ako ključ nedostaje, nije ispravan ili je opozvan, dobit ćete:

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

uz HTTP 401.

Ograničenja broja zahtjeva

Svaki ključ ima dopušten broj zahtjeva po minuti, određen njegovom API razinom (dodjeljuje se pri izdavanju ključa):

Razina	Zahtjevi / minuta
Besplatno	60
Pro	600
Institutional	6 000

Svaki odgovor uključuje standardna zaglavlja kako biste mogli sami regulirati broj zahtjeva:

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

Prekoračenje ograničenja vraća HTTP 429 uz { "ok": false, "error": "rate_limited", "tier": "…" } i zaglavlje Retry-After (sekunde). Pričekajte pa pokušajte ponovno.

Verzioniranje

Sve pristupne točke nalaze se pod /api/v1/. Strukturu odgovora v1 smatramo stabilnim ugovorom — nova polja mogu se dodavati, ali postojeća neće promijeniti značenje niti nestati bez nove verzije (/api/v2/). Pouzdano razvijajte na verziji v1.

---

Pristupne točke

GET /api/v1/meta`

Potvrđuje da vaš ključ radi i navodi čemu može pristupiti.

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`

Rangirani screener za više tržišta — isti mehanizam koji pokreće karticu Screener u aplikaciji.

Parametri upita

Parametar	Zadano	Opis
tf	1d	Vremenski okvir: 5m, 15m, 1h, 4h, 1d
limit	100	Broj redaka za vraćanje (najviše 500)
minScore	0	Vrati samo retke s ocjenom ≥ ovoj vrijednosti

Primjer

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

Pregled polja

Polje	Značenje
symbol	Par na burzi ili ticker
asset_class	Klasa imovine u retku (primjerice crypto, stock, index, commodity)
category	Vrsta setupa (bull, bear-rally, sweep-confirmed, …)
direction	long, short ili null
score	Složena Formion ocjena, 0–100
win_probability	Kalibrirana vjerojatnost modela da je signal točan na horizontu vremenskog okvira ili null ako model nije zadovoljio prag točnosti
rsi_1d	Dnevni RSI(14)
tags	Oznake strukture + momentuma (FVG, BoS/CHoCH, VWAP, zaokreti Adaptive-RSI, …)
scanned_at	Vrijeme temeljnog skeniranja u Unix ms (podaci mogu biti stari do nekoliko minuta)

Te dvije pristupne točke (/meta i /screener) trenutačno čine cijeli v1 API. Ako trebate druge podatke, recite nam koje — zasad nema obveze uvođenja dodatnih pristupnih točaka.

---

Odgovorno korištenje

• Razumno koristite predmemoriju i provjeravajte podatke. Screener ponovno skenira svakih nekoliko minuta; češće provjere samo troše vašu kvotu zahtjeva na iste podatke. Pročitajte scanned_at i preskočite provjeru ako se nije promijenio.
• Jedan ključ po sustavu. Nemojte dijeliti ključ među klijentima — mjerenje potrošnje po ključu omogućuje nama (i vama) praćenje korištenja.
• Nikad ne stavljajte ključ u preglednik ili javni repozitorij. Ako ključ procuri, javite nam se e-poštom kako bismo ga opozvali i izdali novi.

Dobivanje ključa

Pošaljite e-poruku na [email protected] s opisom svoje namjene i očekivanim volumenom zahtjeva. Izdat ćemo vam ključ, dodijeliti mu razinu i pomoći vam da prvi poziv proradi.