Intégrer l'API imaraAI
Guide destiné à qui consomme l'API : front-end, application mobile, ou client tiers sur l'offre Pro. Il décrit les conventions transverses d'abord — elles valent pour tous les endpoints — puis chaque domaine fonctionnel.
La référence exhaustive et toujours à jour est le schéma OpenAPI :
http://localhost:8000/docs en développement. Il est fermé en production :
la surface d'une API est une information à ne pas offrir. Ce document est la
version narrative, celle qui explique pourquoi un endpoint se comporte comme
il le fait.
Avertissement produit. Aucun endpoint ne renvoie de recommandation d'achat ou de vente. Le schéma de sortie de l'analyse IA ne comporte volontairement aucun champ pouvant en loger une, et cette contrainte est vérifiée par les tests. Toute interface construite sur cette API doit afficher le
disclaimerrenvoyé par/me,/analysiset/scanner/latest.
Table des matières
- Conventions transverses
- Authentification
- Compte, offres et quotas
- Dashboard
- Données de marché
- Analyse IA
- Chat IA en streaming SSE
- Scanner de marché
- Actualités et sentiment
- Listes de suivi
- Alertes
- Journal de trading
- Gestion du risque
- Abonnement et paiement
- Administration
- Client TypeScript de référence
- Aide-mémoire des codes d'erreur
1. Conventions transverses
URL de base et versionnage
http://localhost:8000/api/v1 développement
https://api.imaraia.com/api/v1 production
La version est dans le chemin. Une rupture de compatibilité donnera /api/v2,
servi en parallèle : aucune modification incompatible ne sera jamais appliquée à
/api/v1.
Les sondes de santé sont hors préfixe : /health, /health/ready,
/health/version.
Format
JSON en entrée comme en sortie, UTF-8. Les dates sont ISO 8601 en UTC avec
fuseau explicite (2026-08-02T14:30:00Z). Les identifiants sont des UUID v4.
Les montants monétaires sont des chaînes de caractères, pas des nombres :
{ "quantity": "0.42815000", "risk_amount": "150.00" }
Un float JSON est un flottant IEEE 754 : 0.1 + 0.2 !== 0.3. Sur des tailles
de position et des P&L, cette imprécision s'accumule et finit par afficher un
chiffre faux à l'utilisateur. Les données de marché (prix, indicateurs) restent
en nombres — elles alimentent des calculs statistiques, pas de la comptabilité.
Enveloppe d'erreur
Toutes les erreurs partagent une forme unique. Un client n'a jamais qu'un seul format à analyser :
{
"error": {
"code": "plan_limit_reached",
"message": "Limite quotidienne atteinte (5 analysis/jour).",
"details": {
"feature": "analysis",
"limit": 5,
"resets_at": "2026-08-03T00:00:00Z"
}
},
"request_id": "9328e84bc3084f3c84a629a76aa7e2e0"
}
| Champ | Usage |
|---|---|
error.code |
La seule chose sur laquelle brancher du code. Stable, en snake_case |
error.message |
Français, destiné à l'utilisateur final. Le libellé peut changer sans préavis |
error.details |
Contexte structuré, propre au code. Voir le tableau du §17 |
request_id |
À afficher dans un message d'erreur technique et à joindre à tout signalement |
Ne branchez jamais sur error.message : il est susceptible d'être reformulé,
traduit ou raccourci. error.code ne l'est pas.
Corrélation des requêtes
Chaque réponse porte un en-tête X-Request-ID. Si vous en envoyez un, il est
repris ; sinon il est généré. Il apparaît dans chaque ligne de log serveur de la
requête, ce qui rend un incident traçable de bout en bout.
X-Request-ID: 9328e84bc3084f3c84a629a76aa7e2e0
Server-Timing: app;dur=42.13
Limitation de débit
Une fenêtre glissante d'une minute, par utilisateur authentifié ou par IP :
| Appelant | Limite par défaut |
|---|---|
| Anonyme (par IP) | 30 req/min |
| Authentifié (par compte) | 120 req/min |
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 37
Au dépassement : 429 rate_limited avec un en-tête Retry-After en secondes.
Respectez-le. Le limiteur est fail-open : si Redis tombe, il laisse passer
plutôt que de bloquer l'API — ne comptez pas sur lui pour cadencer vos appels.
La limitation de débit et les quotas sont deux mécanismes distincts. Le premier protège le serveur et se réinitialise à la minute ; les seconds matérialisent l'offre commerciale et se réinitialisent à minuit UTC. Voir §3.
Pagination
Les listes longues utilisent limit et offset :
GET /api/v1/journal/trades?limit=20&offset=40
{ "items": [...], "total": 137, "limit": 20, "offset": 40 }
Les listes bornées par nature (listes de suivi, alertes, sessions de chat) renvoient un tableau nu : paginer une collection qui compte au maximum 200 éléments ajoute un aller-retour sans rien résoudre.
Vocabulaire
Symboles. Une seule graphie canonique : BASE/QUOTE pour les paires
(BTC/USD, EUR/USD), le ticker nu pour les actions (AAPL). BTC-USD est
accepté et normalisé ; les particularités des fournisseurs (BTCUSDT chez
Binance) ne remontent jamais jusqu'à vous.
Un symbole hors grammaire est refusé en 400 invalid_symbol plutôt que
« nettoyé » : il est interpolé dans des URL amont et sert de clé de cache.
Unités de temps. 15m, 1h, 4h, 1d, 1w. L'offre gratuite exclut
15m.
Énumérations.
| Champ | Valeurs |
|---|---|
trend |
strong_bearish, bearish, neutral, bullish, strong_bullish |
risk_level |
low, moderate, high, extreme |
sentiment |
very_negative, negative, neutral, positive, very_positive |
direction |
long, short |
status (trade) |
open, closed, canceled |
plan |
free, premium, pro |
asset_class |
crypto, stock, forex, index, commodity |
Le score, et ce qu'il n'est pas
score vaut 0 à 100 et mesure la force et la cohérence de la lecture
technique. Ce n'est pas une probabilité de gain. 50 signifie « aucun biais
directionnel visible », pas « conserver ».
Il est produit par une somme pondérée déterministe, pas par un modèle de langage : il est donc reproductible, auditable et rejouable à partir de l'instantané stocké. Toute interface qui l'affiche doit en donner la lecture correcte — un « 82 / 100 » présenté sans contexte sera lu comme « 82 % de chances de gagner », ce qui serait faux et, sur ce produit, problématique.
2. Authentification
Jetons porteurs (Bearer) sur toutes les routes sauf l'inscription, la
connexion, le rafraîchissement, les routes Google et le webhook Stripe.
Authorization: Bearer <access_token>
| Jeton | Durée | Nature |
|---|---|---|
access_token |
15 min | JWT signé HS256, porte role et plan |
refresh_token |
30 jours | Chaîne opaque, stockée hachée en SHA-256, à rotation |
Le jeton d'accès est court par nécessité : ses revendications sont un instantané. Une montée en gamme ou une désactivation de compte ne prend pleinement effet qu'au rafraîchissement suivant — sauf la désactivation, qui est immédiate parce que la ligne utilisateur est relue à chaque requête.
Inscription
POST /api/v1/auth/register
{
"email": "trader@example.com",
"password": "un-mot-de-passe-solide-42",
"full_name": "Alex Martin",
"experience_level": "beginner",
"accept_disclaimer": true
}
accept_disclaimer est obligatoire et doit valoir true : sans lui,
400 disclaimer_required. La date d'acceptation est conservée — le produit doit
pouvoir prouver qu'aucun gain n'a jamais été promis.
Le mot de passe fait au minimum 10 caractères, ne figure pas dans une liste de
mots de passe courants, et ne contient pas la partie locale de l'adresse email.
Les refus sont explicites : password_too_short, password_too_common,
password_contains_email.
Réponse 201 : l'objet utilisateur. Pas de jetons — enchaînez sur
/auth/login. Le compte est créé complet (abonnement gratuit, profil de risque,
liste de suivi par défaut), donc aucun écran n'a à gérer un utilisateur
à moitié initialisé.
Connexion
POST /api/v1/auth/login
{ "email": "trader@example.com", "password": "un-mot-de-passe-solide-42" }
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"refresh_token": "kR3n_x9…",
"token_type": "bearer",
"expires_in": 900
}
Une adresse inconnue et un mot de passe faux renvoient le même
401 unauthenticated en un temps identique : l'endpoint ne doit pas permettre de
savoir quelles adresses ont un compte.
Rafraîchissement, et la règle qui compte
POST /api/v1/auth/refresh
{ "refresh_token": "kR3n_x9…" }
Renvoie une nouvelle paire. L'ancien jeton de rafraîchissement est révoqué dans la foulée.
Rejouer un jeton déjà tourné révoque toutes les sessions du compte. Un jeton qui a servi et qui resurgit signifie que sa valeur a fuité ; l'hypothèse sûre est le vol. La réponse est
401 refresh_reusedet l'utilisateur doit se reconnecter partout.Conséquence pour votre client : sérialisez les rafraîchissements. Deux requêtes qui expirent en même temps et déclenchent chacune un
/auth/refreshavec le même jeton déconnecteront l'utilisateur. Le client de référence du §16 montre le verrou à mettre en place — ce n'est pas une optimisation, c'est une condition de correction.
Autres codes : refresh_invalid (inconnu), refresh_expired (au-delà de 30
jours), account_disabled.
Déconnexion
POST /api/v1/auth/logout { "refresh_token": "…" } # cet appareil
POST /api/v1/auth/logout-all # tous les appareils
Changement de mot de passe
POST /api/v1/auth/password
{ "current_password": "…", "new_password": "…" }
Toutes les autres sessions sont déconnectées. Sur un compte créé via Google :
400 no_password_set.
Connexion Google (OAuth 2.0 + PKCE)
Trois étapes. La troisième existe pour une raison précise, détaillée plus bas.
1 — Obtenir l'URL d'autorisation
GET /api/v1/auth/google/authorize?redirect_after=/dashboard
{
"authorization_url": "https://accounts.google.com/o/oauth2/v2/auth?...",
"state": "8f3c…"
}
Renvoyé en JSON plutôt qu'en 302 pour que vous puissiez choisir entre une
redirection et une fenêtre surgissante. Redirigez le navigateur vers
authorization_url.
2 — Google renvoie vers l'API
GET /api/v1/auth/google/callback est géré par le serveur. Il vérifie le
state (à usage unique), échange le code, résout le compte, puis redirige
vers votre front-end :
https://imaraia.com/auth/callback?code=<code_a_usage_unique>&next=/dashboard
En cas d'abandon ou de refus : ?error=access_denied.
3 — Échanger le code contre la paire de jetons
POST /api/v1/auth/google/exchange
{ "code": "<code_a_usage_unique>" }
Renvoie la même structure que /auth/login.
Pourquoi ce détour plutôt qu'un jeton dans l'URL de redirection ? Une URL de redirection atterrit dans l'historique du navigateur, dans l'en-tête
Refererde la requête suivante, et dans les journaux de tout proxy sur le trajet. Un code à usage unique valable 90 secondes survit à ces trois fuites. Un jeton de rafraîchissement de 30 jours, non.
Rattachement de compte. Si l'adresse Google correspond à un compte existant,
les deux sont liés — uniquement si Google atteste que l'adresse est
vérifiée. Sinon : 401 oauth_email_unverified. Sans ce contrôle, quiconque
peut déclarer une adresse non vérifiée chez un fournisseur d'identité
prendrait le contrôle du compte correspondant.
Sans configuration Google sur l'instance, ces routes renvoient
503 oauth_not_configured et la connexion par mot de passe fonctionne
normalement.
Mot de passe oublié et vérification d'adresse
POST /api/v1/auth/password/forgot {"email": "…"} → 202, même réponse que le compte existe ou non
POST /api/v1/auth/password/reset {"token": "…", "new_password": "…"}
POST /api/v1/auth/email/verify {"token": "…"}
POST /api/v1/auth/email/verify/resend (authentifié)
Les liens envoyés pointent vers WEB_BASE_URL/reinitialiser?token=… et
/verifier-email?token=…. Un lien de réinitialisation expire après
PASSWORD_RESET_TTL_MINUTES (30) et ne sert qu'une fois : il porte l'empreinte
du mot de passe courant. Une réinitialisation déconnecte toutes les sessions.
Erreurs : 400 invalid_link, 400 link_expired. L'inscription envoie le lien
de vérification.
Clés d'API (offre Pro)
Pour un script, un tableur ou un outil interne, utilisez une clé d'API plutôt qu'une session : elle ne expire pas et ne demande pas de mot de passe. Elle se crée dans Paramètres › API, ou par l'API depuis une session :
GET /api/v1/api-keys
POST /api/v1/api-keys { "name": "Mon script" }
DELETE /api/v1/api-keys/{id}
La réponse de création contient le champ key (imara_sk_…). Il n'est
renvoyé qu'une fois : le serveur ne garde qu'une empreinte SHA-256 et ne peut
pas le relire. Dix clés actives au maximum (402 api_key_limit_reached).
Envoyez la clé dans l'un ou l'autre de ces en-têtes :
X-API-Key: imara_sk_…
Authorization: Bearer imara_sk_…
curl https://api.imaraia.com/api/v1/analysis \
-H "X-API-Key: $IMARA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"symbol": "EUR/USD", "timeframe": "4h"}'
Règles :
- Offre Pro requise. Créer une clé sans l'offre répond
402 api_access_not_included. Si l'abonnement repasse en dessous de Pro, les clés existantes sont conservées mais répondent ce même402jusqu'au retour de l'offre. - Mêmes droits que le compte, moins la gestion du compte. Une clé lit et
écrit les données métier (analyses, chat, journal, alertes, listes de suivi,
risque…) avec les quotas quotidiens de l'offre. Elle est refusée —
403 api_key_not_allowed— sur la gestion du compte (PATCH /me,/me/*, mot de passe, déconnexion globale), les clés elles-mêmes, la facturation et la console d'administration. - Limite de débit propre : 60 requêtes par minute et par clé par défaut
(
RATE_LIMIT_API_KEY_PER_MINUTE), indépendamment de la session web. - Révocation immédiate : une clé révoquée répond
401 api_key_invaliddès la requête suivante.
3. Compte, offres et quotas
Le premier appel de votre application
GET /api/v1/me
{
"user": {
"id": "0193…", "email": "trader@example.com", "full_name": "Alex Martin",
"avatar_url": "https://lh3.googleusercontent.com/a/…",
"locale": "fr", "role": "user", "experience_level": "beginner",
"is_email_verified": false, "created_at": "…", "last_login_at": "…",
"subscription": { "plan": "free", "status": "active", "current_period_end": null,
"cancel_at_period_end": false }
},
"entitlements": {
"plan": "free", "price_eur_monthly": 0,
"max_watchlist_items": 5, "max_alerts": 3,
"timeframes": ["1d", "1h", "1w", "4h"],
"scanner_enabled": false, "journal_ai_review": false,
"news_sentiment": false, "api_access": false,
"tags": ["Analyses limitées", "Actifs sélectionnés"]
},
"quotas": [
{ "feature": "analysis", "used": 2, "limit": 5, "remaining": 3,
"resets_at": "2026-08-03T00:00:00Z" },
{ "feature": "chat_message", "used": 7, "limit": 15, "remaining": 8,
"resets_at": "2026-08-03T00:00:00Z" },
{ "feature": "scanner_run", "used": 0, "limit": 0, "remaining": 0,
"resets_at": "…" },
{ "feature": "journal_review", "used": 0, "limit": 0, "remaining": 0,
"resets_at": "…" }
],
"disclaimer": "imaraAI fournit des analyses éducatives et informatives. …"
}
Identité, droits et quotas restants en un seul appel : un tableau de bord a besoin des trois pour s'afficher, et trois allers-retours au chargement, ce sont trois occasions d'afficher une interface à moitié rendue.
avatar_url est la photo renvoyée par le fournisseur d'identité, rafraîchie
à chaque connexion fédérée. Elle vaut null pour un compte créé par mot de
passe, et l'API ne l'héberge pas : c'est une URL chez le fournisseur, qui peut
cesser de répondre. Prévoyez un repli — les initiales — plutôt qu'une image
cassée. Le champ n'est pas modifiable par PATCH /me : laisser un client
choisir l'URL affichée sur nos pages reviendrait à accepter une image arbitraire
sur notre propre origine.
Comment lire les quotas :
limit: null→ illimité sur cette offre.limit: 0→ fonctionnalité absente de l'offre. Affichez une incitation à monter en gamme, pas un compteur à zéro.remaining→ à afficher tel quel.resets_at→ minuit UTC. Pensez à convertir dans le fuseau de l'utilisateur.
Grille tarifaire publique
GET /api/v1/plans # aucune authentification requise
Générée à partir de la table que le serveur applique réellement. Un écart entre la page tarifaire et les limites appliquées est structurellement impossible.
| Gratuit | Premium (19 €) | Pro (49 €) | |
|---|---|---|---|
| Analyses / jour | 5 | 100 | illimité |
| Messages chat / jour | 15 | 300 | illimité |
| Passages scanner / jour | — | 20 | 200 |
| Revues IA du journal / jour | — | 5 | 30 |
| Actifs par liste | 5 | 50 | 500 |
| Alertes actives | 3 | 30 | 200 |
| Unités de temps | 1h → 1s | toutes | toutes |
| Sentiment des news | — | ✅ | ✅ |
| Accès API | — | — | ✅ |
| Rétention de l'historique | 7 j | 365 j | 1095 j |
Modifier son profil
PATCH /api/v1/me
{ "full_name": "Alex M.", "experience_level": "intermediate", "locale": "fr" }
experience_level (beginner / intermediate / advanced) n'est pas
cosmétique : il pilote la profondeur et le ton de toutes les explications IA.
4. Dashboard
GET /api/v1/dashboard
Un appel, toutes les tuiles : identité, droits, quotas, liste de suivi valorisée, tête du classement scanner, dernières actualités, alertes non lues, humeur de marché, résumé du journal, analyses récentes.
Chaque section peut être vide indépendamment. Une section en échec est renvoyée vide plutôt que de faire tomber la page — un pipeline de news en panne grise une tuile, il ne renvoie pas un 500.
Cet endpoint ne consomme aucun quota. Il lit ce qui existe déjà : le dernier
balayage, les analyses stockées, les cotations en cache. Il ne déclenche jamais
d'analyse pour remplir une carte, sinon un simple rafraîchissement de page
consommerait le quota que l'utilisateur est venu dépenser délibérément. Les
champs trend / score / risk_level d'une ligne de watchlist sont donc null
tant qu'aucune analyse récente (< 24 h) n'existe pour cet actif.
Sur l'offre gratuite, top_opportunities est vide et les champs de sentiment des
actualités sont retirés.
5. Données de marché
Aucun de ces endpoints ne consomme de quota : ce sont des données mises en cache et de l'arithmétique, pas des appels de modèle.
| Classe d'actifs | Fournisseurs, dans l'ordre essayé |
|---|---|
| Crypto | Binance (sans clé), puis Twelve Data |
| Forex, actions, indices | fournisseurs configurés d'abord : Polygon, Twelve Data, Alpha Vantage |
Métaux (XAU/USD, XAG/USD) |
Twelve Data uniquement |
Le champ provider de chaque cotation ou série dit qui a répondu. Un
fournisseur qui refuse (quota, clé sans accès à la donnée) passe la main au
suivant.
Recherche
GET /api/v1/market/search?query=bitcoin
Interroge tous les fournisseurs configurés et fusionne les réponses. Un fournisseur indisponible ne vide pas la liste.
Cotation
GET /api/v1/market/quote/BTC/USD
Le symbole peut contenir une barre oblique : la route l'accepte telle quelle.
{
"symbol": "BTC/USD", "price": 71234.5,
"change_24h": 1250.3, "change_pct_24h": 1.78,
"high_24h": 71890.0, "low_24h": 69120.0, "volume_24h": 28450.12,
"as_of": "2026-08-02T14:29:58Z", "provider": "binance"
}
Surveillez as_of : sur les actions, la donnée provient de la dernière séance
close, pas du temps réel. Affichez la fraîcheur plutôt que de laisser croire à
une cotation vivante.
Chandeliers
GET /api/v1/market/candles/BTC/USD?timeframe=1d&limit=300
limit entre 60 et 1000, 300 par défaut — assez pour une moyenne mobile 200
périodes avec de la marge pour la voir s'incurver.
Instantané technique
GET /api/v1/market/indicators/BTC/USD?timeframe=1d
La lecture technique sans la narration IA, et sans coût de quota. C'est
exactement l'instantané que le modèle reçoit pour l'analyse complète : RSI, MACD,
EMA/SMA, Bollinger, ATR, volatilité annualisée, supports et résistances
regroupés, trend, score, risk_level, et une liste d'observations
factuelles en français.
Utilisez-le pour tout affichage graphique. Réservez /analysis (§6) aux moments
où l'utilisateur demande explicitement une explication.
Historique insuffisant (< 60 chandeliers) : 400 insufficient_history.
6. Analyse IA
POST /api/v1/analysis
{ "symbol": "BTC/USD", "timeframe": "1d", "force_refresh": false }
Consomme une unité de quota analysis — sauf si une analyse récente du même
actif sur la même unité de temps est renvoyée depuis l'historique. Le chandelier
sous-jacent n'ayant pas clôturé, une seconde analyse dirait la même chose ;
force_refresh: true force le recalcul et consomme une unité.
{
"id": "0193…",
"asset": { "id": "…", "symbol": "BTC/USD", "name": "BTC/USD",
"asset_class": "crypto", "exchange": "Binance" },
"timeframe": "1d",
"trend": "bullish", "score": 68, "risk_level": "moderate",
"price_at_analysis": "71234.50000000",
"indicators": { "indicators": {...}, "levels": {...}, "signals": [...],
"candles_used": 300, "provider": "binance" },
"narrative": {
"summary": "…",
"bullish_scenario": "…",
"bearish_scenario": "…",
"risks": ["…", "…", "…"],
"key_points": ["…", "…"],
"invalidation": "…",
"conclusion": "…",
"educational_note": "…"
},
"model": "claude-opus-5",
"created_at": "2026-08-02T14:30:00Z",
"disclaimer": "…"
}
Ce que narrative ne contient pas est aussi important que ce qu'il contient :
il n'y a ni champ recommendation, ni action, ni target_price. Le modèle ne
peut pas émettre de conseil parce qu'il n'a nulle part où le mettre.
indicators conserve l'instantané exact soumis au modèle. Une analyse vieille de
six mois reste donc rejouable et vérifiable : on sait sur quoi elle s'appuyait.
Si la couche statistique est active et qu'un modèle est déployé, indicators
contient en plus score_before_ml et un bloc ml (probabilités, type de modèle,
horizon). Le classifieur ne peut déplacer le score que d'une fraction bornée —
la somme pondérée reste la colonne vertébrale.
Historique
GET /api/v1/analysis/history?limit=20&offset=0
Élagué selon la rétention de l'offre par une tâche de fond.
Erreurs propres : 402 plan_limit_reached (quota épuisé, ou unité de temps hors
offre), 503 ai_not_configured, 502 ai_refusal, 400 insufficient_history.
7. Chat IA en streaming SSE
POST /api/v1/chat/stream
Accept: text/event-stream
{ "message": "Analyse Bitcoin aujourd'hui", "session_id": null }
session_id omis ou null démarre une conversation. Consomme une unité de
quota chat_message.
La réponse est un flux text/event-stream. Chaque événement est une ligne
data: contenant un objet JSON :
data: {"type":"session","session_id":"0193…","context_symbols":["BTC/USD"]}
data: {"type":"delta","text":"Le "}
data: {"type":"delta","text":"Bitcoin "}
data: {"type":"done","usage":{"input_tokens":1240,"output_tokens":380,"latency_ms":4210}}
type |
Quand | Contenu |
|---|---|---|
session |
Toujours en premier | session_id à conserver, et context_symbols : les symboles réellement consultés pour ce tour |
delta |
0..n | Fragment de texte, à concaténer |
done |
Fin normale | Comptage de jetons |
error |
Fin en échec | message prêt à afficher |
context_symbols mérite d'être affiché : il distingue une réponse appuyée sur
des cotations réelles d'une réponse purement conceptuelle. Le modèle a pour
consigne de le dire, mais le champ le prouve.
Points d'implémentation
N'utilisez pas EventSource. L'API native du navigateur ne fait que des
GET et ne permet pas d'en-tête Authorization. Utilisez fetch avec lecture
du corps en flux — le §16 en donne l'implémentation.
La transaction est validée avant le début du flux. Le message de l'utilisateur et le quota consommé survivent à une déconnexion en cours de génération. Une réponse coupée à mi-parcours n'est donc pas rejouable gratuitement : c'est délibéré, sans quoi une boucle de reconnexion ferait grimper la facture fournisseur.
Derrière un proxy, la mise en tampon doit être désactivée. L'API envoie déjà
X-Accel-Buffering: no et Cache-Control: no-cache ; l'ingress fourni dans
deploy/k8s/ est configuré en conséquence.
Sessions
GET /api/v1/chat/sessions
GET /api/v1/chat/sessions/{session_id} # avec tous les messages
DELETE /api/v1/chat/sessions/{session_id}
8. Scanner de marché
Réservé aux offres Premium et Pro : 402 feature_not_in_plan sinon.
Lire le dernier balayage
GET /api/v1/scanner/latest?timeframe=1d&limit=25
Gratuit en quota. La partie coûteuse a déjà eu lieu, une fois, pour tout le monde. Seul le déclenchement d'un nouveau balayage est décompté.
{
"run": { "id": "…", "timeframe": "1d", "status": "completed",
"universe_size": 50, "scanned_count": 48, "failed_count": 2,
"started_at": "…", "finished_at": "…", "created_at": "…" },
"results": [
{
"rank": 1,
"asset": { "symbol": "SOL/USD", "name": "Solana", "asset_class": "crypto" },
"opportunity_score": 84.5,
"conviction_score": 79,
"trend": "bullish", "risk_level": "high",
"price": 182.4, "change_pct": 2.1, "volatility_pct": 4.8,
"reasons": [
"Score de conviction 79/100 — tendance haussière.",
"Croisement MACD haussier sur la dernière bougie.",
"Le prix évolue à proximité immédiate d'un niveau clé.",
"Volatilité high : le dimensionnement de position doit en tenir compte."
],
"indicators": { "rsi_14": 63.2, "macd_histogram": 0.84, "atr_pct": 4.8, "…": null }
}
],
"disclaimer": "…"
}
failed_count compte les actifs qu'aucun fournisseur n'a pu servir sur ce
passage. Un classement sur 48 actifs sur 50 est publié : c'est plus utile qu'une
page d'erreur.
opportunity_score mesure la force et la cohérence de la lecture, pas une
probabilité de gain. Il est symétrique : une lecture franchement baissière
classe aussi haut qu'une lecture franchement haussière. Un scanner qui ne
remonterait que du haussier serait inutilisable à la vente. Affichez toujours
reasons à côté — c'est ce qui rend le rang défendable.
Aucun balayage disponible : 404 no_scan_available.
Déclencher un balayage
POST /api/v1/scanner/run
{ "timeframe": "1d" }
Consomme une unité scanner_run. Réponse 202 :
{ "run": { "id": "0193…", "status": "pending", … }, "job_id": "arq:…" }
Un balayage prend des minutes et des centaines d'appels fournisseurs ; il est exécuté par le worker. Interrogez l'état :
GET /api/v1/scanner/runs/{run_id}
status : pending → running → completed (ou failed). Sondez toutes les
10 à 15 secondes ; ne bloquez pas d'écran dessus.
job_id à null signifie que le worker était indisponible — le run reste
pending et le passage planifié suivant prendra le relais. À traiter comme une
information, pas comme une erreur.
9. Actualités et sentiment
GET /api/v1/news?limit=20&offset=0&symbol=BTC/USD&sentiment=positive
{
"items": [
{
"id": "…", "source": "CoinDesk",
"title": "…", "url": "https://…",
"published_at": "2026-08-02T09:12:00Z",
"summary": "…",
"sentiment": "positive", "sentiment_score": "0.4500",
"impact": { "horizon": "short", "magnitude": "medium", "rationale": "…" },
"related_symbols": ["BTC/USD"],
"analyzed_at": "2026-08-02T09:18:00Z"
}
],
"total": 240, "limit": 20, "offset": 0,
"sentiment_available": true
}
Les titres sont servis à tout le monde ; le sentiment est la partie payante.
Sur l'offre gratuite, sentiment_available vaut false et les champs
sentiment, sentiment_score, impact, related_symbols et analyzed_at sont
null ou vides — les filtres symbol et sentiment sont alors ignorés.
Le drapeau existe pour que le client n'ait jamais à deviner : un sentiment nul
avec sentiment_available: true signifie « pas encore classé », avec false
« non inclus dans votre offre ». Montrer la forme du mur payant convertit mieux
que faire semblant que la donnée n'existe pas.
Humeur agrégée
GET /api/v1/news/sentiment?hours=24 # Premium / Pro
{
"window_hours": 24, "articles": 42,
"counts": { "very_negative": 2, "negative": 7, "neutral": 18,
"positive": 12, "very_positive": 3 },
"average_score": 0.155, "mood": "positif",
"disclaimer": "…"
}
Seuls les articles classés entrent dans le calcul : compter les articles non analysés tirerait l'humeur vers le neutre précisément quand le classifieur prend du retard, c'est-à-dire au moment où il est le moins fiable.
En dessous de trois articles, mood vaut indeterminé. Trois dépêches ne sont
pas une humeur de marché, et une jauge confiante construite sur un seul titre est
pire que pas de jauge.
10. Listes de suivi
GET /api/v1/watchlists
POST /api/v1/watchlists { "name": "Crypto majeures" }
DELETE /api/v1/watchlists/{id}
POST /api/v1/watchlists/{id}/items { "symbol": "BTC/USD" }
DELETE /api/v1/watchlists/{id}/items/{asset_id}
GET /api/v1/watchlists/{id}/quotes
Une liste par défaut est créée à l'inscription. /quotes joint chaque ligne à sa
cotation :
[ { "asset": {...}, "quote": {...} },
{ "asset": {...}, "quote": null } ]
quote: null signale que le fournisseur a échoué sur ce symbole. Le reste de
la liste s'affiche : un tableau de bord avec neuf tuiles vivantes et une tuile
figée est bien plus utile qu'une page d'erreur.
Dépassement du nombre d'actifs autorisé : 402 plan_limit_reached.
11. Alertes
GET /api/v1/alerts?active_only=true
POST /api/v1/alerts
GET /api/v1/alerts/{id}
PATCH /api/v1/alerts/{id}
DELETE /api/v1/alerts/{id}
{
"symbol": "BTC/USD",
"kind": "price_above",
"condition": { "threshold": 75000 },
"label": "Objectif long terme"
}
kind |
condition |
Évaluation |
|---|---|---|
price_above |
{"threshold": 75000} |
cotation |
price_below |
{"threshold": 60000} |
cotation |
percent_move |
{"percent": 5} |
variation 24 h, dans un sens ou l'autre |
rsi_cross |
{"level": 70, "direction": "above"} |
série 1 h |
conviction_score |
{"min_score": 75, "direction": "bullish"} |
score de conviction, série 1 h |
trend_pullback |
{"timeframe": "4h", "direction": "both"} |
setup « tendance + repli » du backtest, dernière bougie clôturée ; une seule alerte par bougie |
La condition est validée à l'écriture, pas à l'évaluation. Une condition
malformée découverte par le worker à trois heures du matin est une alerte qui ne
se déclenche jamais, sans que l'utilisateur puisse comprendre pourquoi. Erreurs :
400 invalid_alert_condition avec la liste des clés manquantes dans details.
Notifications
GET /api/v1/alerts/triggers?unread_only=true&limit=50
POST /api/v1/alerts/triggers/acknowledge
[
{
"id": "…", "alert_id": "…",
"triggered_at": "2026-08-02T11:04:00Z",
"price": 75120.0,
"message": "BTC/USD a atteint 75120, au-dessus du seuil 75000.",
"context": { "threshold": 75000, "price": 75120.0 },
"acknowledged_at": null
}
]
Cette liste reste l'enregistrement de référence. Quand l'instance a un
TELEGRAM_BOT_TOKENet que l'utilisateur a lié un chat, chaque déclenchement est aussi poussé sur Telegram, au mieux : un envoi raté est journalisé, jamais rejoué, et n'annule pas le déclenchement.
PUT /api/v1/me/telegram {"chat_id": "123456789"} # null pour délier
Réponse : {"chat_id": "123456789", "bot_configured": true, "test_sent": true}.
Chaque semaine (lundi 06:00 UTC par défaut), un résumé du journal est poussé
aux utilisateurs liés qui ont clôturé au moins un trade.
Un message de test part à l'enregistrement ; 400 invalid_telegram_chat si
l'identifiant n'est pas un entier (ou un @canal).
Le worker évalue les alertes toutes les 5 minutes. Une alerte qui vient de se déclencher observe un délai de garde (60 minutes par défaut) : sans lui, un prix qui oscille autour d'un seuil notifierait à chaque passage.
12. Journal de trading
Trades
POST /api/v1/journal/trades
{
"symbol": "BTC/USD", "direction": "long",
"quantity": "0.5", "entry_price": "68000",
"stop_loss": "66000", "take_profit": "74000",
"opened_at": "2026-08-01T09:00:00Z",
"setup": "breakout", "emotion": "confiant", "followed_plan": true,
"notes": "Cassure de la résistance hebdomadaire."
}
stop_loss est facultatif mais sans lui le R-multiple ne peut pas être
calculé — et le R-multiple est la seule métrique qui compare équitablement des
trades de tailles différentes.
GET /api/v1/journal/trades?trade_status=open&limit=20&offset=0
GET /api/v1/journal/trades/{id}
PATCH /api/v1/journal/trades/{id}
DELETE /api/v1/journal/trades/{id}
POST /api/v1/journal/trades/{id}/close
{ "exit_price": "72500", "closed_at": "…", "fees": "12.40",
"notes": "…", "followed_plan": true }
À la clôture, pnl, pnl_pct et r_multiple sont calculés une fois et
figés. Les recalculer à la lecture laisserait un changement ultérieur de profil
de risque réécrire l'histoire d'un trade terminé. Trade déjà clos :
409 trade_already_closed.
Captures d'écran — trois étapes
Le fichier ne transite jamais par l'API.
1 — Demander un ticket
POST /api/v1/journal/uploads/screenshot
{ "content_type": "image/png", "size_bytes": 184320 }
{
"upload_url": "https://bucket.s3.eu-west-3.amazonaws.com/…&X-Amz-Signature=…",
"object_key": "screenshots/<user_id>/9f2c….png",
"method": "PUT",
"headers": { "Content-Type": "image/png", "Content-Length": "184320" },
"max_bytes": 5242880,
"expires_at": "2026-08-02T14:35:00Z"
}
2 — Envoyer le fichier directement au stockage
await fetch(ticket.upload_url, {
method: ticket.method,
headers: ticket.headers, // les deux en-têtes sont signés : ne les modifiez pas
body: file,
});
3 — Rattacher au trade
POST /api/v1/journal/trades/{id}/screenshot
{ "object_key": "screenshots/<user_id>/9f2c….png" }
Renvoie le trade avec screenshot_url renseigné.
Formats acceptés : image/png, image/jpeg, image/webp. Pas de SVG : c'est
un format de document qui exécute du script, et il serait servi depuis notre
propre origine. Taille maximale 5 Mo, signée dans l'URL — un envoi d'une autre
taille est rejeté par le stockage lui-même.
La clé d'objet est vérifiée avant rattachement : elle doit être sous le préfixe
de l'utilisateur, sinon 403 object_not_owned. Les clés circulent dans les URL
et l'historique du navigateur ; en connaître une ne prouve rien.
Sans stockage configuré : 503 storage_not_configured, et le journal fonctionne
sans images.
Statistiques de processus
GET /api/v1/journal/statistics
{
"trades_total": 42, "trades_closed": 38, "trades_open": 4,
"win_rate_pct": "57.8900", "average_win": "312.40", "average_loss": "-186.20",
"profit_factor": "1.6200", "expectancy_r": "0.3400",
"net_pnl": "4218.60", "best_trade": "1450.00", "worst_trade": "-720.00",
"stop_usage_pct": "92.8500", "plan_adherence_pct": "71.4200"
}
Tout décrit un comportement — usage du stop, respect du plan, espérance en R — plutôt qu'une performance à afficher. Un journal qui ne rapporte que le P&L n'apprend rien sur les raisons de ce P&L.
Revue IA
POST /api/v1/journal/reviews
{ "period_days": 30 }
Premium et Pro. Consomme une unité journal_review. Minimum 5 trades sur la
période, sinon 400 not_enough_trades : en dessous, une « erreur récurrente »
est une coïncidence.
{
"id": "…", "period_start": "…", "period_end": "…",
"trades_analyzed": 23,
"discipline_score": 74,
"statistics": {
"…": "…",
"discipline": {
"score": 74,
"components": { "stop_usage": 92, "plan_adherence": 71, "risk_consistency": 55 },
"sample_size": 23
}
},
"findings": {
"top_mistakes": [
{ "title": "Stop déplacé sous pression",
"evidence": "Trades des 3, 11 et 19 juillet.",
"impact": "…", "correction": "…" }
],
"strengths": ["…"],
"recommendations": ["…"],
"summary": "…"
},
"model": "claude-opus-5",
"created_at": "…"
}
discipline_scoreest calculé, pas généré. Usage du stop (40 %), respect du plan (35 %), régularité du risque (25 %). Le modèle le reçoit et l'explique ; il ne le décide pas. Un utilisateur qui conteste sa note doit pouvoir pointer la composante responsable — d'oùstatistics.discipline.components, à afficher à côté du score.Aucune composante ne regarde le P&L. Un mois rentable mais indiscipliné note mal : c'est tout l'objet de la métrique.
GET /api/v1/journal/reviews?limit=10&offset=0
Import MetaTrader 5
POST /api/v1/journal/import/mt5
{"content": "<contenu du CSV>", "dry_run": false}
Lit l'export de l'onglet Historique (vue Positions) ou tout CSV aux colonnes
équivalentes — séparateur, en-têtes français ou anglais, colonnes Time/Price
dupliquées. Seules les positions clôturées sont importées ; le P&L est celui du
fichier (profit + commission + swap). Le ticket est conservé : réimporter le
même fichier ne crée aucun doublon. Réponse : parsed, imported,
duplicates, skipped, errors (ligne et raison).
400 invalid_import_file si l'en-tête est introuvable.
Les statistiques (GET /journal/statistics) incluent désormais
max_drawdown, max_drawdown_r et max_consecutive_losses.
Analyse par dimension et export
GET /api/v1/journal/breakdown?by=setup|symbol|direction|weekday|hour|emotion&days=90
GET /api/v1/journal/export.csv
Le découpage ne porte que sur les trades clos, trié par espérance en R (jour
et heure d'entrée en UTC). L'export est un CSV séparé par ;, UTF-8 avec BOM
pour Excel.
Checklist pré-trade
pre_trade_checklist (liste de questions) vit dans le profil de risque.
POST /journal/trades accepte checklist_checked ; la réponse porte
checklist: {items, checked}, et un followed_plan absent est déduit
(toutes les cases cochées = plan respecté).
13. Gestion du risque
Profil
GET /api/v1/risk/profile
PATCH /api/v1/risk/profile
{
"account_balance": "10000", "currency": "EUR",
"risk_per_trade_pct": "1.0", "max_daily_loss_pct": "3.0",
"max_drawdown_pct": "15.0", "max_open_positions": 5,
"min_reward_risk_ratio": "1.5"
}
Dimensionnement de position
POST /api/v1/risk/position-size
{ "entry_price": "68000", "stop_loss": "66000",
"direction": "long", "take_profit": "74000" }
{
"quantity": "0.05000000",
"risk_amount": "100.00", "risk_pct_of_account": "1.0000",
"position_value": "3400.00",
"stop_distance": "2000.00", "stop_distance_pct": "2.9412",
"reward_risk_ratio": "3.0000", "potential_profit": "300.00",
"breakeven_win_rate_pct": "25.0000",
"warnings": [],
"disclaimer": "…"
}
account_balance et risk_per_trade_pct reprennent le profil si vous ne les
fournissez pas.
warnings liste les règles de votre propre profil que ce plan enfreint.
C'est informatif : le calcul n'est jamais bloqué. L'outil signale, il
n'interdit pas — c'est l'utilisateur qui trade.
breakeven_win_rate_pct est le taux de réussite minimal pour être à l'équilibre
avec ce ratio. C'est souvent le chiffre le plus instructif de la réponse.
État du risque
GET /api/v1/risk/status
Profil, nombre de positions ouvertes, perte journalière (avec breached) et
drawdown calculé sur la courbe d'équité reconstituée à partir des trades clos.
Garde-fou
GET /api/v1/risk/guard?symbol=EUR/USD
Une ligne par règle — daily_loss, consecutive_losses, drawdown,
open_positions, economic_calendar, trading_hours — avec un statut ok,
warn ou block,
et le pire des statuts en tête. Les réglages vivent dans le profil de risque :
guard_mode (warn | block), max_consecutive_losses (0 = désactivé),
news_blackout_minutes. En mode block, POST /journal/trades répond
409 risk_guard_blocked (verdict complet dans details) tant qu'une règle est
enfreinte ; un trade daté de plus d'une heure est un enregistrement a
posteriori et n'est jamais bloqué. /risk/status et les deux calculateurs
renvoient aussi le verdict dans guard.
GET /api/v1/calendar?impact=high&hours=48&symbol=EUR/USD
Annonces à venir (flux hebdomadaire au format Forex Factory, mis en cache une
heure). available: false quand le flux est injoignable.
Horaires de trading
PATCH /api/v1/risk/profile
{"schedule_enabled": true, "schedule_timezone": "Europe/London",
"schedule_windows": [{"days": [1,2,3,4,5], "start": "08:00", "end": "12:00"}]}
GET /api/v1/risk/schedule/presets
Jours ISO (1 = lundi). Une fin antérieure au début franchit minuit et appartient
au jour où la plage commence. Hors plage, la règle trading_hours du garde-fou
avertit ou bloque selon guard_mode et donne la prochaine ouverture ; les
déclenchements d'alerte sont conservés mais pas poussés sur Telegram.
400 invalid_trading_schedule / invalid_timezone sur une saisie invalide.
Taille de position en lots
GET /api/v1/risk/instruments
POST /api/v1/risk/lot-size
{ "symbol": "EURUSD", "stop_pips": 20, "risk_per_trade_pct": 1 }
Capital, devise et risque retombent sur le profil. Le stop se donne en pips
(stop_pips) ou en prix (entry_price + stop_loss). Conventions MetaTrader :
forex 100 000 unités/lot (pip 0,0001, 0,01 sur le yen), or 100 oz (pip 0,10),
argent 5 000 oz, indices 1 × point. contract_size et pip_size surchargent
celles du courtier. La taille est arrondie vers le bas au pas de lot ; sous
le lot minimum, lots vaut 0 et un avertissement donne le risque qu'imposerait
ce minimum. Quand l'instrument n'est coté ni dans la devise du compte ni dans sa
devise de base, le taux est lu sur le marché ou exigé
(400 conversion_rate_required).
Backtest
POST /api/v1/backtest
{ "symbol": "BTC/USD", "timeframe": "4h", "candles": 1000,
"strategy": "trend_pullback", "atr_stop_multiple": 1.5, "reward_risk": 2 }
Chaque exécution est enregistrée (sauf "save": false) ; les 50 dernières
sont gardées :
GET /api/v1/backtest/runs?symbol=EUR/USD
GET /api/v1/backtest/runs/{id} # avec la courbe de capital
DELETE /api/v1/backtest/runs/{id}
Une alerte trend_pullback avec "require_backtest": true n'est acceptée que
si le dernier backtest de ce setup, sur ce symbole et cette unité de temps,
compte au moins 20 trades et une espérance positive
(400 backtest_required / backtest_not_positive).
Stratégies : trend_pullback (EMA50 > EMA200, repli rejeté sur l'EMA20 sur une
bougie haussière, miroir en vente) et ema_cross. Entrée à l'ouverture de la
bougie suivante, stop supposé touché en premier quand une bougie touche stop
et objectif, sortie à l'ouverture sur un gap. Statistiques en R et sur un compte
à risque fixe : espérance, taux de réussite, facteur de profit, drawdown, pire
série, rendement comparé à l'achat-conservation. Moins de 30 trades ou une
espérance négative produisent un avertissement explicite.
400 not_enough_candles, 402 pour une unité de temps hors offre.
14. Abonnement et paiement
État courant
GET /api/v1/billing/subscription
{
"plan": "premium", "status": "past_due",
"effective_plan": "free",
"current_period_end": "2026-09-01T00:00:00Z",
"cancel_at_period_end": false,
"trial_ends_at": null,
"is_managed_by_stripe": true
}
Utilisez effective_plan pour les droits, plan pour l'affichage. Un
abonnement impayé ou annulé conserve son libellé mais retombe sur free pour les
droits — ce qui rend une reprise de paiement transparente, sans réattribution.
Souscrire
POST /api/v1/billing/checkout
{ "plan": "premium" }
{ "checkout_url": "https://checkout.stripe.com/c/pay/cs_…", "plan": "premium" }
Redirigez vers checkout_url.
La page de succès n'accorde rien. Elle prouve qu'un navigateur a été redirigé, pas qu'un paiement a abouti. L'offre change quand — et seulement quand — un webhook signé le dit. Après le retour de l'utilisateur, sondez
GET /billing/subscriptionpendant quelques secondes plutôt que de supposer la montée en gamme effectuée.
409 already_subscribed si l'offre demandée est déjà active. 400 plan_is_free
pour free.
Gérer son abonnement
POST /api/v1/billing/portal
Renvoie une URL vers le portail client Stripe : résiliation, changement de carte, factures. Ces trois opérations ne sont pas réimplémentées ici — chacune est un endroit où un bug coûte de l'argent réel, et la version de Stripe est déjà conforme PCI.
404 no_stripe_customer si le compte n'a jamais eu d'abonnement payant.
Webhook — configuration serveur
POST /api/v1/billing/webhook
Non authentifié par nécessité : la signature du corps brut est l'authentification. À configurer côté Stripe sur ces événements :
checkout.session.completed
customer.subscription.created
customer.subscription.updated
customer.subscription.deleted
invoice.payment_failed
En développement :
stripe listen --forward-to localhost:8000/api/v1/billing/webhook
L'endpoint est idempotent (chaque identifiant d'événement n'est appliqué qu'une
fois) et insensible à l'ordre (un événement plus ancien que le dernier appliqué
est ignoré). Il répond 200 pour tout ce qu'il comprend, y compris les doublons
et les événements ignorés : un non-2xx ferait rejouer Stripe pendant des jours.
Sans Stripe configuré, /checkout et /portal renvoient
503 billing_not_configured et tout le monde reste sur l'offre gratuite.
15. Administration
Réservé au rôle admin (403 permission_denied sinon). Le rôle n'est attribué
par aucun endpoint : c'est une opération d'exploitation, en base.
GET /api/v1/admin/overview
GET /api/v1/admin/users?search=trader&limit=50&offset=0
POST /api/v1/admin/users/{id}/deactivate
POST /api/v1/admin/users/{id}/reactivate
POST /api/v1/admin/jobs/{job_name}
overview renvoie des compteurs lus en direct : utilisateurs, répartition par
offre, analyses et messages sur 24 h, passages scanner, articles non classés,
alertes actives, manifeste du modèle statistique chargé.
Aucun endpoint ne modifie un abonnement. Stripe est la source de vérité de ce qu'un client paie ; une offre éditée à la main serait silencieusement écrasée par le webhook suivant.
jobs/{job_name} accepte une liste blanche fermée (run_scan, ingest_news,
classify_news, evaluate_alerts, purge_expired, purge_news, purge_scans,
train_models). Un nom libre ferait de cet endpoint une exécution de code à
distance par procuration.
Un administrateur ne peut pas désactiver son propre compte :
400 cannot_self_deactivate.
Publications sur les réseaux sociaux
GET /api/v1/admin/social/status
GET /api/v1/admin/social/posts
POST /api/v1/admin/social/posts { "template": "analyse|citation|offre" }
POST /api/v1/admin/social/posts/{id}/approve { "caption": "…" }
POST /api/v1/admin/social/posts/{id}/skip
GET /api/v1/social/media/{id}/square.jpg (public)
GET /api/v1/social/media/{id}/landscape.jpg (public)
Le visuel du jour est préparé par le worker (tâche social_daily, aussi
déclenchable depuis POST /admin/jobs/social_daily). Voir le README de l'API
pour la configuration de Facebook, Instagram et X.
Revenus, consommation IA et journal d'audit
GET /api/v1/admin/revenue
GET /api/v1/admin/ai-usage?days=30
GET /api/v1/admin/audit?limit=100&kind=all|action|setting
revenue— revenu mensuel récurrent (MRR) et annuel, abonnés payants par offre, essais, paiements en échec, résiliations programmées, et les 20 derniers événements Stripe. Calculé depuis le miroir local des abonnements : seuls les statuts qui donnent accès (active,trialing) comptent comme revenu.ai-usage— jetons d'entrée et de sortie des analyses et des réponses du chat, par jour, par modèle et par compte (les 20 plus coûteux), avec un coût estimé à partir deAI_COST_INPUT_USD_PER_MTOKetAI_COST_OUTPUT_USD_PER_MTOK(modifiables depuis la console).audit— les actions de la console (user.deactivate,user.reactivate,billing.resync,job.trigger) et les modifications de configuration, la plus récente en tête. Append-only : aucun endpoint ne supprime une ligne.
16. Client TypeScript de référence
Rien d'exhaustif : les trois points où une implémentation naïve casse.
Rafraîchissement sérialisé
type Tokens = { access_token: string; refresh_token: string; expires_in: number };
export class ImaraClient {
private tokens: Tokens | null = null;
/** Le verrou : sans lui, deux 401 simultanés déconnectent l'utilisateur. */
private refreshing: Promise<Tokens> | null = null;
constructor(private readonly baseUrl = "/api/v1") {}
/** Exposé pour le flux de chat, qui construit sa requête lui-même. */
get accessToken(): string {
if (!this.tokens) throw new Error("Non authentifié.");
return this.tokens.access_token;
}
private async refresh(): Promise<Tokens> {
// Un rafraîchissement déjà en vol ? On s'y raccroche.
// Deux appels concurrents à /auth/refresh présentent le même jeton ; le
// second est vu comme un rejeu et révoque toutes les sessions du compte.
if (this.refreshing) return this.refreshing;
this.refreshing = (async () => {
const response = await fetch(`${this.baseUrl}/auth/refresh`, {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ refresh_token: this.tokens!.refresh_token }),
});
if (!response.ok) {
this.tokens = null;
throw new ImaraError(await response.json());
}
this.tokens = await response.json();
return this.tokens!;
})();
try {
return await this.refreshing;
} finally {
this.refreshing = null;
}
}
async request<T>(path: string, init: RequestInit = {}, retry = true): Promise<T> {
const response = await fetch(`${this.baseUrl}${path}`, {
...init,
headers: {
"Content-Type": "application/json",
...(this.tokens && { Authorization: `Bearer ${this.tokens.access_token}` }),
...init.headers,
},
});
if (response.status === 401 && retry && this.tokens?.refresh_token) {
await this.refresh();
return this.request<T>(path, init, false);
}
if (response.status === 429) {
// Le serveur dit combien de temps attendre. Écoutez-le.
const after = Number(response.headers.get("Retry-After") ?? 5);
await new Promise((resolve) => setTimeout(resolve, after * 1000));
return this.request<T>(path, init, retry);
}
if (!response.ok) throw new ImaraError(await response.json());
return response.json();
}
}
/** Porte `code` et `requestId` : c'est sur eux que le code se branche. */
export class ImaraError extends Error {
readonly code: string;
readonly details: Record<string, unknown>;
readonly requestId: string | null;
constructor(payload: any) {
super(payload?.error?.message ?? "Erreur inconnue");
this.code = payload?.error?.code ?? "unknown_error";
this.details = payload?.error?.details ?? {};
this.requestId = payload?.request_id ?? null;
}
}
Consommer le flux de chat
type ChatEvent =
| { type: "session"; session_id: string; context_symbols: string[] }
| { type: "delta"; text: string }
| { type: "done"; usage: { input_tokens: number; output_tokens: number } | null }
| { type: "error"; message: string };
export async function* streamChat(
client: ImaraClient,
message: string,
sessionId: string | null,
signal?: AbortSignal,
): AsyncGenerator<ChatEvent> {
// `EventSource` ne sait faire que des GET sans en-tête : inutilisable ici.
const response = await fetch("/api/v1/chat/stream", {
method: "POST",
headers: {
"Content-Type": "application/json",
Authorization: `Bearer ${client.accessToken}`,
Accept: "text/event-stream",
},
body: JSON.stringify({ message, session_id: sessionId }),
signal,
});
if (!response.ok) throw new ImaraError(await response.json());
const reader = response.body!.getReader();
const decoder = new TextDecoder();
let buffer = "";
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
// Les événements sont séparés par une ligne vide, et un chunk réseau peut
// couper n'importe où : on ne traite que les événements complets.
const events = buffer.split("\n\n");
buffer = events.pop() ?? "";
for (const event of events) {
const line = event.split("\n").find((l) => l.startsWith("data: "));
if (line) yield JSON.parse(line.slice(6)) as ChatEvent;
}
}
}
Usage :
let answer = "";
for await (const event of streamChat(client, "Analyse Bitcoin", null)) {
if (event.type === "session") setSessionId(event.session_id);
else if (event.type === "delta") setAnswer((answer += event.text));
else if (event.type === "error") showError(event.message);
}
Traiter les limites d'offre
try {
await client.request("/analysis", {
method: "POST",
body: JSON.stringify({ symbol: "BTC/USD", timeframe: "1d" }),
});
} catch (error) {
if (error instanceof ImaraError) {
switch (error.code) {
case "feature_not_in_plan":
// Absente de l'offre : proposer la montée en gamme.
return showUpgrade(error.details.feature as string);
case "plan_limit_reached":
// Incluse mais épuisée : dire quand elle revient.
return showQuotaExhausted(error.details.resets_at as string);
case "insufficient_history":
return showMessage("Historique insuffisant pour cet actif.");
case "ai_not_configured":
return showMessage("Analyse IA temporairement indisponible.");
}
}
throw error;
}
feature_not_in_plan et plan_limit_reached partagent le statut 402 mais
appellent deux écrans différents : « passez à Premium » contre « revenez
demain ». Les confondre est la façon la plus simple de rater une conversion ou
d'en forcer une inutile.
17. Aide-mémoire des codes d'erreur
| Statut | code |
Signification | Réaction du client |
|---|---|---|---|
| 400 | bad_request |
Requête invalide | Afficher message |
| 400 | invalid_symbol |
Symbole hors grammaire | Corriger la saisie |
| 400 | insufficient_history |
Moins de 60 chandeliers | Proposer une autre unité de temps |
| 400 | not_enough_trades |
Moins de 5 trades sur la période | Indiquer le minimum |
| 400 | invalid_alert_condition |
Condition incomplète ou hors bornes | details.missing |
| 400 | disclaimer_required |
Avertissement non accepté | Bloquer l'inscription |
| 400 | password_too_short / _too_common / _contains_email |
Mot de passe refusé | Message dédié |
| 400 | file_too_large / unsupported_media_type |
Envoi refusé | details.max_bytes, details.accepted |
| 400 | cannot_self_deactivate |
Auto-désactivation admin | — |
| 400 | invalid_exit_quantity |
Sortie supérieure au reste | Afficher le reste |
| 400 | invalid_prop_rules |
Règles de challenge incohérentes | Afficher message |
| 400 | default_account |
Archivage du compte par défaut | Changer de compte par défaut |
| 400 | confirmation_required / wrong_password |
Suppression de compte non confirmée | Redemander |
| 400 | totp_invalid / totp_not_started / totp_already_on |
Mise en place de la 2FA | Redemander le code |
| 400 | backtest_not_positive |
Bot sans backtest positif | Renvoyer vers /backtest |
| 400 | bot_position_open |
Suppression d'un bot en position | Attendre la sortie |
| 400 | metaapi_not_linked |
Compte sans identifiant MetaApi | Demander l'identifiant |
| 401 | totp_required / totp_invalid |
Connexion avec 2FA | Afficher le champ code |
| 401 | token_missing / token_invalid / token_expired |
Jeton d'accès | Rafraîchir |
| 401 | refresh_invalid / refresh_expired |
Jeton de rafraîchissement | Reconnexion |
| 401 | refresh_reused |
Rejeu détecté, sessions révoquées | Reconnexion + avertissement sécurité |
| 401 | unauthenticated |
Identifiants faux | Message générique |
| 401 | api_key_invalid |
Clé d'API inconnue ou révoquée | Créer une nouvelle clé |
| 402 | api_access_not_included |
Clé d'API hors offre Pro | Proposer l'offre Pro |
| 402 | api_key_limit_reached |
Dix clés actives déjà | Révoquer une clé |
| 403 | api_key_not_allowed |
Gestion du compte avec une clé d'API | Utiliser une session |
| 401 | use_oauth_login |
Compte Google sans mot de passe | Rediriger vers Google |
| 401 | oauth_state_invalid / oauth_code_invalid |
Flux expiré ou rejoué | Recommencer |
| 401 | oauth_email_unverified |
Adresse non vérifiée chez le fournisseur | Proposer le mot de passe |
| 402 | plan_limit_reached |
Quota épuisé | details.resets_at |
| 402 | feature_not_in_plan |
Hors offre | Écran de montée en gamme |
| 403 | permission_denied |
Rôle insuffisant | — |
| 403 | object_not_owned |
Clé d'objet d'un autre compte | — |
| 404 | not_found |
Ressource absente | — |
| 404 | no_scan_available |
Aucun balayage terminé | État vide |
| 404 | no_stripe_customer |
Pas d'abonnement payant | Masquer le portail |
| 409 | conflict |
Conflit d'état | — |
| 409 | email_taken |
Adresse déjà inscrite | Proposer la connexion |
| 409 | trade_already_closed |
Trade déjà clos | Rafraîchir |
| 409 | already_subscribed |
Offre déjà active | — |
| 422 | validation_error |
Champs invalides | details.fields[] |
| 429 | rate_limited |
Débit dépassé | Respecter Retry-After |
| 502 | upstream_error |
Fournisseur en échec | Réessayer plus tard |
| 502 | ai_refusal / ai_truncated / ai_invalid_json |
Modèle | Proposer une reformulation |
| 503 | ai_not_configured |
Pas de clé IA | Masquer les fonctions IA |
| 503 | provider_not_configured |
Pas de clé marché | Masquer la classe d'actifs |
| 503 | billing_not_configured |
Pas de Stripe | Masquer la souscription |
| 503 | oauth_not_configured |
Pas de Google | Masquer le bouton |
| 503 | storage_not_configured |
Pas de stockage | Masquer l'envoi d'images |
| 503 | metaapi_not_configured |
Pas de METAAPI_TOKEN |
Masquer la synchronisation |
| 503 | service_unavailable |
Dégradation générale | Réessayer |
18. Compte, comptes de trading, notifications et bot démo
Assistant de démarrage
GET /me renvoie onboarding_completed_at. Tant qu'il est null, le front
redirige vers /bienvenue.
POST /api/v1/me/onboarding
{ "account_balance": "10000", "currency": "USD", "risk_per_trade_pct": "1",
"max_daily_loss_pct": "3", "account_name": "Principal", "account_kind": "real" }
POST /api/v1/me/onboarding/skip
L'assistant écrit le profil de risque et crée le compte de trading par défaut. « Plus tard » marque seulement l'étape comme vue.
Données personnelles (RGPD)
GET /api/v1/me/export → JSON en pièce jointe, sans aucun secret
DELETE /api/v1/me { "confirm": "SUPPRIMER", "password": "…" }
password est exigé si le compte en a un (has_password dans /me), sinon
400 wrong_password. Sans le mot SUPPRIMER, la réponse est
400 confirmation_required. La suppression résilie l'abonnement Stripe, efface
toutes les données en cascade, puis les captures d'écran dans le stockage.
Double authentification (TOTP)
POST /api/v1/me/2fa/setup → { "secret", "otpauth_uri", "qr_svg" }
POST /api/v1/me/2fa/enable { "code": "123456" } → { "recovery_codes": [10 codes] }
POST /api/v1/me/2fa/disable { "code": "123456 | xxxx-xxxx" }
Une fois la 2FA active, POST /auth/login sans totp_code renvoie
401 totp_required, et un code faux 401 totp_invalid. Un code de secours
remplace le code à 6 chiffres, une seule fois. Un même code TOTP ne sert
jamais deux fois. La connexion Google n'est pas concernée : elle s'appuie sur
la 2FA du compte Google.
Comptes de trading et règles de prop firm
GET /api/v1/accounts → comptes avec status { equity, net_pnl, closed_trades, prop }
GET /api/v1/accounts/prop-presets → ftmo, ftmo_verification, trailing_generic
POST /api/v1/accounts { name, kind: demo|real|prop, currency, starting_balance, prop_rules? }
PATCH /api/v1/accounts/{id} { name?, is_default?, prop_rules?, metaapi_account_id? }
DELETE /api/v1/accounts/{id} → archive (les trades restent)
POST /api/v1/accounts/{id}/sync → import MetaApi immédiat
prop_rules accepte max_daily_loss_pct (perte du jour rapportée au solde
de début de journée), max_total_loss_pct, drawdown_mode: static|trailing,
profit_target_pct et min_trading_days. Le statut prop.status vaut
in_progress, passed ou failed. Le garde-fou (GET /risk/guard?account_id=)
ajoute alors une règle prop_rules, qui bloque avant que la limite du
challenge ne soit franchie.
Le journal, les statistiques, l'analyse par dimension et l'export CSV
acceptent ?account_id=. Le compte par défaut inclut aussi les trades
antérieurs, sans compte. Le compte par défaut ne peut pas être archivé
(400 default_account).
Sorties partielles et erreurs d'exécution
POST /api/v1/journal/trades/{id}/exits { "quantity": "1", "exit_price": "1.1050", "fees"? }
POST /api/v1/journal/trades/{id}/close { "exit_price", "mistakes": ["early_exit", …] }
GET /api/v1/journal/mistakes → { code: libellé }
GET /api/v1/journal/breakdown?by=mistake
close sort la quantité restante. Le trade reste open tant qu'il reste une
quantité. Le R final se calcule sur le prix de sortie moyen pondéré et sur
initial_stop_loss, le premier stop connu, qu'un stop déplacé ensuite ne
modifie pas. Une quantité supérieure au reste renvoie
400 invalid_exit_quantity.
Notifications push (PWA)
GET /api/v1/me/push/key → { "public_key" } (VAPID)
POST /api/v1/me/push/subscriptions { endpoint, keys: { p256dh, auth } }
POST /api/v1/me/push/unsubscribe { endpoint }
POST /api/v1/me/push/test
Les alertes déclenchées partent en push sur chaque appareil abonné, dans les
horaires de trading. Un abonnement expiré (404/410 du service push) est
supprimé automatiquement. Il faut configurer VAPID_PUBLIC_KEY,
VAPID_PRIVATE_KEY et VAPID_SUBJECT.
Synchronisation MetaTrader 5 (MetaApi)
Renseignez l'identifiant de compte MetaApi sur un compte de trading
(metaapi_account_id). Le worker importe ensuite les positions clôturées
chaque heure, à la minute 25 : 90 jours d'historique la première fois, puis
avec un recouvrement de 2 jours. Les doublons sont écartés par
external_id = mt5:{positionId}. Il faut définir METAAPI_TOKEN. Les erreurs
possibles sont metaapi_not_configured, metaapi_not_linked et
502 metaapi_error, cette dernière aussi visible dans sync_error sur le
compte.
Bot démo (testnet Binance)
GET /api/v1/bots
POST /api/v1/bots { symbol, timeframe: 1h|4h|1d, risk_pct ≤ 2, starting_balance, api_key, api_secret }
PATCH /api/v1/bots/{id} { "enabled": true }
POST /api/v1/bots/{id}/run
DELETE /api/v1/bots/{id}
- Testnet uniquement : l'adresse
https://testnet.binance.visionest figée dans le code, et une clé de compte réel n'y fonctionne pas. - Backtest exigé : le dernier backtest « Tendance + repli » de ce symbole
et de cette unité de temps doit compter au moins 30 trades et une espérance
positive. Sinon, la réponse est
400 backtest_not_positive, à la création comme à l'activation. - Le bot est créé en pause, avec un compte de trading démo dédié. Chaque ordre est journalisé et passe d'abord par le garde-fou.
- Les clés sont chiffrées (Fernet dérivé de
SECRET_KEY). ChangerSECRET_KEYles rend illisibles :bot_keys_unreadable, il faut recréer le bot. - On ne peut pas supprimer un bot qui a une position ouverte
(
400 bot_position_open). BOT_TRADING_ENABLED=falsecoupe tous les bots d'un coup.
Notifications par e-mail
Deux préférences sur le compte, lues dans user et modifiables par
PATCH /api/v1/me :
{ "email_alerts_enabled": true, "email_digest_enabled": false }
email_alerts_enabled(désactivé par défaut) — chaque déclenchement d'alerte est aussi envoyé par e-mail, hors des heures de repos du trader.email_digest_enabled(activé par défaut) — résumé hebdomadaire du journal.- Seules les adresses vérifiées reçoivent ces e-mails.
- Les e-mails de facturation (abonnement activé, paiement échoué, résiliation programmée, fin d'abonnement) sont transactionnels et toujours envoyés.
Chaque e-mail de notification porte un lien de désabonnement signé et les
en-têtes List-Unsubscribe / List-Unsubscribe-Post (RFC 8058). Le lien
aboutit à :
POST /api/v1/notifications/unsubscribe { "token": "…" }
Public (le jeton signé est la preuve), idempotent, il coupe une seule
catégorie. Un jeton invalide répond 400 invalid_link.
Langue
PATCH /api/v1/me { "locale": "en" } fait répondre l'IA (analyses et chat) en
anglais. Le français reste la langue par défaut.
Voir aussi
api/README.md— architecture, décisions techniques, exploitationdeploy/k8s/README.md— déploiement et sauvegardeshttp://localhost:8000/docs— schéma OpenAPI interactif (développement)