API dei dati di KURV

L’API dei dati risponde alle domande che un agente o una dashboard fanno su KURV: quante collezioni sono state lanciate, che cosa è stato mintato, che cosa si è mosso, da dove sono arrivate le iscrizioni. È in sola lettura. Una chiave apre solo le route GET sotto /api/v1 e nient’altro: nessuna route qui crea, modifica, firma o spende qualcosa.

Autenticazione

Ogni richiesta porta una chiave API come bearer token:

Authorization: Bearer kurv_sk_...

Le chiavi le crea il team di KURV, una per agente, e vengono mostrate una sola volta al momento della creazione. KURV conserva solo un’impronta, quindi una chiave persa viene sostituita, mai recuperata. Una chiave si può revocare in qualsiasi momento; la sua richiesta successiva viene rifiutata. Le richieste senza chiave, con una chiave revocata o con una chiave priva dell’ambito della route ricevono un 401 o un 403 con una frase che lo spiega.

Ambiti

Ambito	Apre
kurv:stats:read	Le quattro route /api/v1/stats/*: conteggi, volume, commissioni e fonti, senza nessuna e-mail né nessun nome in alcuna risposta
kurv:admin:read	/api/v1/admin/*: le candidature con le loro e-mail, chi ha accettato un invito, chi c’è dietro ogni collezione, i posti usati, l’esportazione giornaliera e i conteggi per fonte

Una chiave ha un ambito oppure entrambi. L’ambito admin è l’unico che riporta e-mail.

Endpoint

Richiesta	Risponde con
GET /api/v1/stats/overview?chain=	Collezioni lanciate, mint, minter unici, volume, commissioni, creator e iscrizioni, ciascuno per le ultime 24 ore, gli ultimi 7 giorni e da sempre
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Ogni collezione lanciata con total_minted, il suo volume per token, il suo ultimo mint e l’account del suo creator, 25 per pagina
GET /api/v1/stats/mints?chain=&since=&cursor=	I mint dal più recente, 50 per pagina, a partire da since
GET /api/v1/stats/users?chain=&since=	Iscrizioni, account per rete, creator e minter attivi, la ripartizione per tag di provenienza e l’imbuto dall’iscrizione al lancio
GET /api/v1/admin/signups?since=&source=	Candidature, account, link di invito con i loro riscatti, conteggi per fonte e lanci che non avevano nessun tag
GET /api/v1/admin/acceptances?since=&source=	Ogni invito accettato, il più recente per primo: l’account, il suo profilo, il suo handle X, un’e-mail quando una candidatura la indica, l’ora e il tag con cui è arrivato
GET /api/v1/admin/creators?chain=&since=	Chi c’è dietro ogni collezione su ogni rete, o su quella indicata da chain: l’account, il suo profilo, il suo handle e il suo handle X quando è noto
GET /api/v1/admin/seats	I posti usati finora, giorno per giorno
GET /api/v1/admin/funnel?chain=&since=	Gli inviti accettati su una rete, per periodo e per tag, e il funnel con essi
GET /api/v1/admin/testers	Tutti quelli entrati e chi ha fatto un rapporto nella guida, con lo stato di ogni compito. Le loro note restano fuori
GET /api/v1/admin/export?day=	L’esportazione scritta ogni giorno alle 6:30 a Guayaquil, quella di quel giorno o la più recente, con i giorni disponibili: le accettazioni, chi crea e i posti, completa fino al momento in cui è stata eseguita

chain indica una rete servita dal deployment, base-sepolia (o il suo chain id, 84532) oppure solana-devnet; se manca, è la chain EVM predefinita. since è in ISO 8601 o in secondi unix. cursor è il pagination.next_cursor della pagina precedente, opaco, e null sull’ultima pagina.

Nelle accettazioni, in chi crea e nell’esportazione, email_basis dice che tipo di e-mail porta una riga. email con founder_tagged_link è verificata: il team di KURV ha etichettato il link per una persona, è stato usato una volta e una candidatura porta il tag. email_claimed con ref_tag_unverified è un’affermazione e mai un’identità: l’account è arrivato da un indirizzo con un tag ref e una candidatura porta quel tag, ma chiunque può scrivere un indirizzo così. I tag precedenti al 30 ottobre 2026 non danno né l’una né l’altra, e nemmeno un nome scritto in un modulo.

Ogni risposta riporta api_version, chain, environment e read_at. Gli importi sono unità di base come stringhe decimali, una voce per token sotto native; usd è la parte in USDC espressa in dollari, oppure null quando si è mosso solo un token senza un valore in dollari. Il denaro in un token non viene mai sommato al denaro in un altro.

Un esempio per ciascuna

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 }

Limiti e aggiornamento

Ogni chiave può fare 120 richieste al minuto, e 30 al minuto su /api/v1/admin/*. Oltre quel limite la risposta è 429 con un header retry-after. Ogni risposta ha al massimo 60 secondi: il server legge una volta al minuto e read_at è l’ora di quella lettura. Per seguire i mint man mano che avvengono, chiama /api/v1/stats/mints ogni 30-60 secondi con since impostato all’ultimo read_at che hai visto; non c’è nessuno stream da tenere aperto.

Che cosa non può fare una chiave

Niente. Una chiave legge. Non può creare una collezione, preparare un lancio, mintare, scambiare, cambiare un profilo né toccare un invito. Un agente che deve creare collezioni si collega invece tramite MCP, con l’approvazione della persona, e quel collegamento è separato da qualsiasi chiave.

Gli errori usano { "api_version": "1", "error": { "code": "...", "message": "..." } } con i codici di stato 400, 401, 403, 429 o 503. Le route pubbliche, senza chiave, sono descritte in API pubbliche; KURV per sviluppatori elenca ogni punto di accesso. Le commissioni in questi dati sono quelle proprie di ogni collezione: leggi Commissioni e Rischi e avvertenze.