Imara AI Docs

Rechercher dans la documentation

Tapez un mot-clé : journal, stop, Telegram, quota…

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 disclaimer renvoyé par /me, /analysis et /scanner/latest.


Table des matières

  1. Conventions transverses
  2. Authentification
  3. Compte, offres et quotas
  4. Dashboard
  5. Données de marché
  6. Analyse IA
  7. Chat IA en streaming SSE
  8. Scanner de marché
  9. Actualités et sentiment
  10. Listes de suivi
  11. Alertes
  12. Journal de trading
  13. Gestion du risque
  14. Abonnement et paiement
  15. Administration
  16. Client TypeScript de référence
  17. 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_reused et 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/refresh avec 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 Referer de 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ême 402 jusqu'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_invalid dè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_TOKEN et 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_score est 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/subscription pendant 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 de AI_COST_INPUT_USD_PER_MTOK et AI_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.vision est 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). Changer SECRET_KEY les 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=false coupe 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, exploitation
  • deploy/k8s/README.md — déploiement et sauvegardes
  • http://localhost:8000/docs — schéma OpenAPI interactif (développement)