API dla deweloperów

Wyślij klucz fom_live_… jako token Bearer: /api/v1/meta potwierdza jego poprawność, /api/v1/screener zwraca ranking screenera w formacie JSON, z nagłówkami limitu żądań w każdej odpowiedzi.

Formion Data API zapewnia programistyczny dostęp do tych samych sygnałów, które widzisz w aplikacji — rankingu screenera, skalibrowanych prawdopodobieństw zysku i innych danych — przez prosty, uwierzytelniany endpoint REST. Jest przeznaczone dla analityków ilościowych, twórców botów i zespołów tradingowych, które chcą wykorzystać przewagę Formion we własnych systemach.

Status: dostępne na życzenie. Klucze są wydawane ręcznie przez zespół Formion. Samodzielne generowanie osobistych tokenów API jest w planach — karta dostępu do API w Profil → Licencja pokazuje Wkrótce. Napisz na [email protected], aby poprosić o klucz.

Uwierzytelnianie

Każde żądanie zawiera klucz API jako token Bearer:

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

Klucze mają postać fom_live_…. Traktuj je jak hasło — każdy, kto ma klucz, może wywoływać API w Twoim imieniu.
Klucz jest pokazywany raz, przy wydaniu, a po naszej stronie przechowywany wyłącznie jako hash. Jeśli go zgubisz, unieważnimy go i wydamy nowy — nie możemy go odzyskać.
Do szybkich testów możesz też przekazać klucz jako ?api_key=…, ale zalecany jest nagłówek Authorization.

Jeśli brakuje klucza, jest on nieprawidłowy lub unieważniony, otrzymasz:

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

z kodem HTTP 401.

Limity żądań

Każdy klucz ma limit żądań na minutę określony przez jego plan API (przypisywany przy wydaniu klucza):

Plan	Żądania / minutę
Free	60
Pro	600
Institutional	6 000

Każda odpowiedź zawiera standardowe nagłówki, dzięki którym możesz samodzielnie ograniczać częstotliwość żądań:

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

Przekroczenie limitu zwraca HTTP 429 z { "ok": false, "error": "rate_limited", "tier": "…" } i nagłówkiem Retry-After (sekundy). Odczekaj i ponów próbę.

Wersjonowanie

Wszystkie endpointy znajdują się pod /api/v1/. Traktujemy strukturę odpowiedzi v1 jako stały kontrakt — nowe pola mogą być dodawane, ale istniejące pola nie zmienią znaczenia ani nie znikną bez nowej wersji (/api/v2/). Możesz śmiało budować integracje z v1.

Endpointy

GET /api/v1/meta`

Potwierdza, że klucz działa, i wyświetla listę dostępnych dla niego endpointów.

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`

Ranking screenera obejmującego wiele rynków — ten sam silnik, który obsługuje zakładkę Screener w aplikacji.

Parametry zapytania

Parametr	Domyślnie	Opis
`tf`	`1d`	Interwał: `5m`, `15m`, `1h`, `4h`, `1d`
`limit`	`100`	Liczba zwracanych wierszy (maks. 500)
`minScore`	`0`	Zwracaj tylko wiersze z oceną ≥ tej wartości

Przykład

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

Opis pól

Pole	Znaczenie
`symbol`	Para na giełdzie lub ticker
`asset_class`	Klasa aktywów danego wiersza (na przykład `crypto`, `stock`, `index`, `commodity`)
`category`	Typ setupu (`bull`, `bear-rally`, `sweep-confirmed`, …)
`direction`	`long`, `short` lub `null`
`score`	Łączna ocena Formion, 0–100
`win_probability`	Skalibrowane prawdopodobieństwo modelu, że sygnał okaże się trafny w horyzoncie danego interwału, lub `null`, jeśli model nie osiągnął wymaganego progu trafności
`rsi_1d`	Dzienny RSI(14)
`tags`	Tagi struktury + momentum (FVG, BoS/CHoCH, VWAP, zwroty Adaptive-RSI, …)
`scanned_at`	Czas bazowego skanu w milisekundach Unix (dane mogą mieć do kilku minut)

Te dwa endpointy (/meta i /screener) to obecnie całe API v1. Jeśli potrzebujesz innych danych, napisz nam jakich — na razie nie zobowiązujemy się do dodania kolejnych endpointów.

Dobre praktyki

Korzystaj z pamięci podręcznej i odpytuj rozsądnie. Screener skanuje rynek co kilka minut; częstsze odpytywanie tylko zużywa limit zapytań na identyczne dane. Odczytuj scanned_at i pomijaj odpytywanie, jeśli wartość się nie zmieniła.
Jeden klucz na system. Nie udostępniaj jednego klucza wielu klientom — pomiar zużycia dla każdego klucza pozwala nam (i Tobie) analizować wykorzystanie.
Nigdy nie umieszczaj klucza w kodzie przeglądarkowym ani publicznym repozytorium. Jeśli klucz wycieknie, napisz do nas, abyśmy mogli go unieważnić i wydać nowy.

Jak uzyskać klucz

Napisz na [email protected], opisując zastosowanie i przewidywany wolumen zapytań. Wydamy klucz, przypiszemy mu poziom dostępu i pomożemy uruchomić pierwsze wywołanie.