Appendix B · API

Complete Vivra server API contract: routes, inputs, outputs, and errors. It supplements the route list on the Project analysis page. All figures in JSON responses below are examples, not live data.

General conventions#

• Base: https://api.<vivra-domain>/v1. UTF-8 JSON throughout.
• On-chain amounts returned as strings (raw units); USD amounts as numbers with 2 decimals in this specification; dates in ISO 8601 UTC.
• Cursor pagination: ?limit=50&cursor=<opaque>, response { "items": [...], "next_cursor": "..." | null }. Maximum limit: 100.
• Voter authentication: vivra_session cookie (HttpOnly, Secure, SameSite=Lax), value = session ID. No token in browser storage.
• Back-office authentication: message signed by a wallet in team_wallets (SIWE, EIP-4361), then a 12 h vivra_admin cookie.
• CORS: dapp and back-office domains only.

Error format#

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

Rate limits#

Public routes (no session required)#

GET /stats#

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

GET /tokens/:address#

Only for a published token (candidate in a published cycle or a token taken over); otherwise 404. Returns the token header, latest snapshot, contract checks, socials, latest recovery score and breakdown, and 90 days of daily history (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 is null without a session or vote.

GET /candidates/:id#

The complete dossier: all blocks from Candidate dossier contents, plus recovery_score (score frozen at publication and its breakdown) and recovery_score_live.

GET /cycles and GET /cycles/:id#

Cycle history with the winner and final results.

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.<vivra-domain>", "x": "https://x.com/…", "telegram": "https://t.me/…" },
  "cto_request": { "status": "submitted" },
  "verdict": null }

GET /operations/:id/log#

Cursor pagination. Each row: { "id", "at", "agent", "kind", "summary", "cost_usd" }. Never payload.

GET /ledger#

Parameters: type, from, to, limit, cursor. Each row: type, token, raw and USD amounts, source and destination wallets, hash, date.

GET /wallets#

Public addresses of all wallets in wallets, with current balances.

Sign-in#

POST /auth/email#

Input: { "email": "[email protected]", "captcha_token": "…" }. Normalizes the email (lowercase, no surrounding spaces), rejects disposable domains, creates or retrieves the user, and emails a six-digit code plus magic link (/auth/magic?token=…). Always responds 204, whether the email exists or not.

POST /auth/verify#

Input: { "email": "[email protected]", "code": "482913" } or { "magic_token": "…" }. Creates a 30-day session and sets the cookie. Response: { "user": { "id": 812, "created_at": "…", "can_vote_at": "…" } }.

POST /auth/logout#

Revokes the current session. 204.

GET /me#

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

Voting and support (session required)#

POST /votes#

Input: { "candidate_id": 17 }. Creates or replaces the user’s vote for that candidate’s cycle. Errors: vote_not_open, vote_closed, account_too_new, forbidden. Response: the updated GET /cycles/current object.

POST /supports and DELETE /supports/:candidate_id#

Input: { "candidate_id": 17 }. Idempotent. Response: { "supports": 413 }.

Real time (WebSocket)#

Connect to wss://api.<vivra-domain>/v1/ws. The client sends { "subscribe": "cycle:4" } or { "subscribe": "operation:4" }. Incoming messages:

Ping every 25 s; automatic client reconnection resumes from the last received id ({ "subscribe": "operation:4", "since": 1532 }).

Back-office (/admin prefix, admin session required)#

Every write to /admin adds a row to admin_audit.