Annexe B · API

Contrat complet de l'API du serveur Vivra : routes, entrées, sorties et erreurs. Il complète la liste de routes de la page Analyse des projets.

Généralités#

• Base : https://api.<domaine-vivra>/v1. JSON partout, en UTF-8.
• Montants on-chain renvoyés en chaîne de caractères (unités brutes) ; montants en USD en nombre à 2 décimales ; dates en ISO 8601 UTC.
• Pagination par curseur : ?limit=50&cursor=<opaque>, réponse { "items": [...], "next_cursor": "..." | null }. limit max 100.
• Auth des votants : cookie vivra_session (HttpOnly, Secure, SameSite=Lax), valeur = id de session. Pas de jeton dans le stockage du navigateur.
• Auth du back-office : signature d'un message par un wallet de team_wallets (SIWE, EIP-4361), puis cookie vivra_admin de 12 h.
• CORS : seulement le domaine de la dapp et celui du back-office.

Format d'erreur#

{ "error": { "code": "vote_closed", "message": "Voting for cycle 4 closed at 2026-11-12T18:00:00Z." } }

Limites de débit#

Routes publiques (sans session)#

GET /stats#

{ "takeovers": 4, "revived": 2, "verdicts": 3,
  "vivra_burned": "1250000000000000000000000", "cto_fees_received_usd": 4210.55 }

GET /tokens/:address#

Seulement pour un token publié (candidat d'un cycle publié ou token repris) ; 404 sinon. Renvoie l'en-tête du token, le dernier instantané, les vérifications de contrat, les socials, le dernier score de reprise avec son détail, et l'historique quotidien sur 90 jours (history: [{ "date", "price_usd", "volume_usd", "holders" }]).

GET /cycles/current#

{ "id": 4, "number": 4, "status": "voting",
  "vote_opens_at": "2026-11-10T18:00:00Z", "vote_closes_at": "2026-11-12T18:00:00Z",
  "voters": 3812,
  "candidates": [ {
    "id": 17, "position": 1, "token": "0x…", "ticker": "GRANDPA",
    "tagline": "…", "thesis_short": "…", "votes": 1290, "share_pct": 33.8,
    "supports": 412, "recovery_score": 68 } ],
  "my_vote": 17 }

my_vote vaut null sans session ou sans vote.

GET /candidates/:id#

La fiche complète : tous les blocs de « Contenu d'une fiche candidat », plus recovery_score (note figée à la publication et son détail) et recovery_score_live.

GET /cycles et GET /cycles/:id#

Historique des cycles, avec le gagnant et les résultats finaux.

GET /operations/:id#

{ "id": 4, "token": "0x…", "ticker": "GRANDPA", "status": "running", "j0": "…",
  "steps": [ { "key": "designer.directions", "agent": "designer", "due_at": "…", "status": "done" } ],
  "spent_usd": 38.12,
  "buyback": { "envelope_wei": "…", "cap_wei": "…", "slices_done": 9, "slices_total": 23, "burned": "…" },
  "links": { "site": "https://grandpa.<domaine-vivra>", "x": "https://x.com/…", "telegram": "https://t.me/…" },
  "cto_request": { "status": "submitted" },
  "verdict": null }

GET /operations/:id/log#

Pagination par curseur. Chaque ligne : { "id", "at", "agent", "kind", "summary", "cost_usd" }. Jamais payload.

GET /ledger#

Paramètres : type, from, to, limit, cursor. Chaque ligne : type, jeton, montant brut et en USD, wallets source et destination, hash, date.

GET /wallets#

Les adresses publiques de tous les wallets de la table wallets, avec leur solde courant.

Connexion#

POST /auth/email#

Entrée : { "email": "a@b.com", "captcha_token": "…" }. Normalise l'email (minuscules, sans espaces), refuse les domaines jetables, crée ou retrouve l'utilisateur, envoie un email contenant un code à 6 chiffres et un lien magique (/auth/magic?token=…). Réponse 204, toujours la même, que l'email existe ou non.

POST /auth/verify#

Entrée : { "email": "a@b.com", "code": "482913" } ou { "magic_token": "…" }. Crée la session (30 jours) et pose le cookie. Réponse { "user": { "id": 812, "created_at": "…", "can_vote_at": "…" } }.

POST /auth/logout#

Révoque la session courante. 204.

GET /me#

{ "id", "created_at", "can_vote_at", "votes": [{ "cycle_id", "candidate_id" }], "supports": [candidate_id] }.

Vote et soutien (session requise)#

POST /votes#

Entrée : { "candidate_id": 17 }. Crée ou remplace le vote de l'utilisateur pour le cycle de ce candidat. Erreurs : vote_not_open, vote_closed, account_too_new, forbidden. Réponse : le même objet que GET /cycles/current, à jour.

POST /supports et DELETE /supports/:candidate_id#

Entrée : { "candidate_id": 17 }. Idempotent. Réponse { "supports": 413 }.

Temps réel (WebSocket)#

Connexion : wss://api.<domaine-vivra>/v1/ws. Le client envoie { "subscribe": "cycle:4" } ou { "subscribe": "operation:4" }. Messages reçus :

Ping toutes les 25 s, reconnexion automatique côté client avec reprise depuis le dernier id reçu ({ "subscribe": "operation:4", "since": 1532 }).

Back-office (préfixe /admin, session admin requise)#

Chaque appel /admin en écriture ajoute une ligne à admin_audit.