API de données KURV

L’API de données répond aux questions qu’un agent ou un tableau de bord se pose sur KURV : combien de collections ont été lancées, ce qui a été minté, ce qui a bougé, d’où viennent les inscriptions. Elle est en lecture seule. Une clé ouvre seulement les routes GET sous /api/v1, et rien d’autre : aucune route ici ne crée, ne modifie, ne signe ni ne dépense quoi que ce soit.

Authentification

Chaque requête porte une clé d’API sous forme de jeton bearer :

Authorization: Bearer kurv_sk_...

Les clés sont créées par l’équipe KURV, une par agent, et affichées une seule fois à leur création. KURV ne conserve qu’une empreinte : une clé perdue est remplacée, jamais récupérée. Une clé peut être révoquée à tout moment ; sa requête suivante est refusée. Les requêtes sans clé, avec une clé révoquée ou avec une clé à laquelle manque la portée de la route reçoivent un 401 ou un 403 avec une phrase qui l’indique.

Portées

Portée	Ouvre
kurv:stats:read	Les quatre routes /api/v1/stats/* : compteurs, volume, frais et sources, sans aucun e-mail ni aucun nom dans les réponses
kurv:admin:read	/api/v1/admin/* : les candidatures avec leurs e-mails, les personnes qui ont accepté une invitation, la personne derrière chaque collection, les places utilisées, l’export quotidien et les compteurs par source

Une clé porte une portée ou les deux. La portée admin est la seule qui donne accès aux e-mails.

Points d’accès

Requête	Répond
GET /api/v1/stats/overview?chain=	Collections lancées, mints, minteurs uniques, volume, frais, créateurs et inscriptions, chacun sur les dernières 24 heures, les 7 derniers jours et depuis le début
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Chaque collection lancée avec total_minted, son volume par jeton, son dernier mint et le compte de son créateur, 25 par page
GET /api/v1/stats/mints?chain=&since=&cursor=	Les mints du plus récent au plus ancien, 50 par page, à partir de since
GET /api/v1/stats/users?chain=&since=	Inscriptions, comptes par réseau, créateurs et minteurs actifs, la répartition par étiquette de source et l’entonnoir de l’inscription au lancement
GET /api/v1/admin/signups?since=&source=	Candidatures, comptes, liens d’invitation avec leurs utilisations, compteurs par source et lancements sans étiquette
GET /api/v1/admin/acceptances?since=&source=	Chaque invitation acceptée, la plus récente d’abord : le compte, son profil, son identifiant X, un e-mail quand une candidature en indique un, l’heure et l’étiquette avec laquelle il est arrivé
GET /api/v1/admin/creators?chain=&since=	La personne derrière chaque collection sur chaque réseau, ou sur celui que chain indique : le compte, son profil, son identifiant et son identifiant X quand il est connu
GET /api/v1/admin/seats	Les places utilisées jusqu’ici, jour après jour
GET /api/v1/admin/funnel?chain=&since=	Les invitations acceptées sur un réseau, par période et par étiquette, et l’entonnoir avec elles
GET /api/v1/admin/testers	Toutes les personnes entrées et celles qui ont fait un rapport dans le guide, avec l’état de chaque tâche. Leurs notes restent à part
GET /api/v1/admin/export?day=	L’export écrit chaque jour à 6:30 à Guayaquil, celui de ce jour ou le plus récent, avec les jours disponibles : les acceptations, les personnes et les places, complet jusqu’au moment de son exécution

chain désigne un réseau servi par le déploiement, base-sepolia (ou son ID de chaîne, 84532) ou solana-devnet ; s’il est omis, c’est la chaîne EVM par défaut. since est au format ISO 8601 ou en secondes Unix. cursor est le pagination.next_cursor de la page précédente, opaque, et vaut null sur la dernière page.

Dans les acceptations, les personnes et l’export, email_basis indique quel type d’e-mail porte une ligne. email avec founder_tagged_link est vérifié : l’équipe KURV a étiqueté le lien pour une personne, il a été utilisé une fois et une candidature porte l’étiquette. email_claimed avec ref_tag_unverified est une affirmation et jamais une identité : le compte est arrivé par une adresse avec une étiquette ref et une candidature porte cette étiquette, mais tout le monde peut saisir une telle adresse. Les étiquettes antérieures au 30 octobre 2026 ne donnent ni l’un ni l’autre, pas plus qu’un identifiant saisi dans un formulaire.

Chaque réponse contient api_version, chain, environment et read_at. Les montants sont en unités de base, sous forme de chaînes décimales, avec une entrée par jeton sous native ; usd est la part en USDC exprimée en dollars, ou null quand seul un jeton sans montant en dollars a bougé. L’argent dans un jeton n’est jamais additionné à l’argent dans un autre.

Un exemple de chaque

curl -H "Authorization: Bearer $KURV_KEY" \
  "https://testnet.kurv.fun/api/v1/stats/overview?chain=base-sepolia"

{ "api_version": "1", "chain": "base-sepolia", "read_at": "2026-10-25T18:02:11.000Z",
  "windows": { "24h": { "collections": { "created": 3, "drafts": 2, "launched": 1 }, "mints": { "events": 12, "pieces": 12 },
    "unique_minters": 9, "volume": { "native": [{ "asset_id": "evm:84532:token:0x036c...", "symbol": "USDC", "decimals": 6, "base_units": "48000000" }], "usd": "48.00" },
    "fees": { "native": [{ "asset_id": "evm:84532:token:0x036c...", "symbol": "USDC", "decimals": 6, "base_units": "2400000" }], "usd": "2.40" },
    "creators": 1, "signups": 3 }, "7d": { }, "all": { } },
  "notes": [ ] }

curl -H "Authorization: Bearer $KURV_KEY" \
  "https://testnet.kurv.fun/api/v1/stats/collections?chain=base-sepolia&sort=volume"

{ "sort": "volume", "collections": [ { "id": "evm:84532:0xabc...", "address": "0xabc...", "name": "MAXCAT", "creator": "0x2787...",
    "launched_at": "2026-10-20T15:00:00.000Z", "total_minted": 120, "volume": { "native": [ ], "usd": "600.00" }, "last_mint_at": "2026-10-25T17:40:02.000Z" } ],
  "pagination": { "limit": 25, "next_cursor": null, "total": 1 } }

curl -H "Authorization: Bearer $KURV_KEY" \
  "https://testnet.kurv.fun/api/v1/stats/mints?chain=base-sepolia&since=2026-10-25T17:00:00Z"

{ "since": "2026-10-25T17:00:00.000Z", "mints": [ { "id": "evm:84532:0xabc...:4200100:3", "collection": "evm:84532:0xabc...", "minter": "0x70997...",
    "pieces": 1, "paid": { "symbol": "USDC", "decimals": 6, "base_units": "5000000" }, "tx": "0x5e2b...", "at": "2026-10-25T17:40:02.000Z" } ],
  "pagination": { "limit": 50, "next_cursor": null } }

curl -H "Authorization: Bearer $KURV_KEY" \
  "https://testnet.kurv.fun/api/v1/stats/users?chain=base-sepolia"

{ "accounts": { "base_sepolia": 34, "solana_devnet": 6 },
  "windows": { "7d": { "signups": 5, "active_creators": 2, "active_minters": 9, "by_source": { "XD-ana": { "signups": 2, "accounts": 1, "launched": 1 } },
    "funnel": { "visits": 40, "submissions": 5, "building": 3, "launched": 2 } } },
  "notes": [ "Visits, sign-ups and the wizard are not per network." ] }

curl -H "Authorization: Bearer $KURV_ADMIN_KEY" \
  "https://testnet.kurv.fun/api/v1/admin/signups?since=2026-10-01&source=XD-ana"

{ "applications": [ { "handle": "ana_builds", "email": "[email protected]", "created_at": "2026-10-24T09:12:00.000Z", "ref": "XD-ana" } ],
  "accounts": { "base_sepolia": 34, "solana_devnet": 6 },
  "invites": [ { "link_id": "3f9c...", "label": "Friends on X", "uses": 12,
    "redemptions": [ { "account": "0x3c44...", "handle": "ana_builds", "accepted_at": "2026-10-24T10:01:00.000Z", "ref": "XD-ana" } ] } ],
  "by_source": { "XD-ana": { "signups": 2, "accepted": 1, "launched": 1 } },
  "launched_outside_outreach": 7 }

Limites et fraîcheur

Chaque clé peut faire 120 requêtes par minute, et 30 par minute sur /api/v1/admin/*. Au-delà, la réponse est un 429 avec un en-tête retry-after. Chaque réponse date d’au plus 60 secondes : le serveur lit une fois par minute et read_at est l’heure de cette lecture. Pour suivre les mints au fil de l’eau, appelez /api/v1/stats/mints toutes les 30 à 60 secondes avec since réglé sur le dernier read_at que vous avez vu ; il n’y a aucun flux à garder ouvert.

Ce qu’une clé ne peut pas faire

Rien. Une clé ne fait que lire. Elle ne peut pas créer de collection, préparer un lancement, minter, échanger, modifier un profil ni toucher à une invitation. Un agent qui doit construire des collections se connecte plutôt via MCP, avec l’approbation de la personne, et cette connexion est distincte de toute clé.

Les erreurs utilisent { "api_version": "1", "error": { "code": "...", "message": "..." } } avec les codes d’état 400, 401, 403, 429 ou 503. Les routes publiques, sans clé, sont décrites dans API publiques ; KURV pour les développeurs liste tous les points d’entrée. Les frais de ces chiffres sont propres à chaque collection : lisez Frais et Risques et avertissement.