Data-API van KURV

De data-API beantwoordt de vragen die een agent of een dashboard over KURV stelt: hoeveel collecties er zijn gelanceerd, wat er is gemint, wat er is verhandeld, waar aanmeldingen vandaan kwamen. Ze kan alleen lezen. Een sleutel opent alleen de GET-routes onder /api/v1 en verder niets: geen enkele route hier maakt, wijzigt, ondertekent of besteedt iets.

Authenticatie

Elk verzoek draagt een API-sleutel als bearer-token:

Authorization: Bearer kurv_sk_...

Sleutels worden gemaakt door het team van KURV, één per agent, en één keer getoond als ze worden gemaakt. KURV bewaart alleen een digest, dus een verloren sleutel wordt vervangen, nooit hersteld. Een sleutel kan op elk moment worden ingetrokken; het volgende verzoek ermee wordt geweigerd. Verzoeken zonder sleutel, met een ingetrokken sleutel of met een sleutel zonder het bereik van de route krijgen een 401 of 403 met één zin die dat zegt.

Bereiken

Bereik	Opent
kurv:stats:read	De vier routes /api/v1/stats/*: aantallen, volume, vergoedingen en bronnen, zonder e-mailadres en zonder naam in enig antwoord
kurv:admin:read	/api/v1/admin/*: aanvragen met hun e-mailadressen, wie een uitnodiging accepteerde, wie achter elke collectie zit, de gebruikte plaatsen, de dagelijkse export en de aantallen per bron

Een sleutel draagt één bereik of allebei. Het beheerbereik is het enige dat e-mailadressen bevat.

Endpoints

Verzoek	Antwoordt met
GET /api/v1/stats/overview?chain=	Gelanceerde collecties, mints, unieke minters, volume, vergoedingen, makers en aanmeldingen, elk voor de laatste 24 uur, de laatste 7 dagen en alle tijd
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Elke gelanceerde collectie met total_minted, haar volume per munt, haar laatste mint en het account van haar maker, 25 per pagina
GET /api/v1/stats/mints?chain=&since=&cursor=	Mints, de nieuwste eerst, 50 per pagina, vanaf since
GET /api/v1/stats/users?chain=&since=	Aanmeldingen, accounts per netwerk, actieve makers en minters, de verdeling per brontag en de trechter van aanmelding tot lancering
GET /api/v1/admin/signups?since=&source=	Aanvragen, accounts, uitnodigingslinks met hun inwisselingen, aantallen per bron en lanceringen zonder tag
GET /api/v1/admin/acceptances?since=&source=	Elke geaccepteerde uitnodiging, de nieuwste eerst: het account, zijn profiel, zijn X-handle, een e-mailadres als een aanvraag er een noemt, de tijd en de tag waarmee het kwam
GET /api/v1/admin/creators?chain=&since=	Wie achter elke collectie zit op elk netwerk, of op het netwerk dat chain noemt: het account, zijn profiel, zijn handle en zijn X-handle als die bekend is
GET /api/v1/admin/seats	De tot nu toe gebruikte plaatsen, dag na dag
GET /api/v1/admin/funnel?chain=&since=	Geaccepteerde uitnodigingen op één netwerk, per periode en per tag, en de trechter erbij
GET /api/v1/admin/testers	Iedereen die binnen is en iedereen die rapporteerde in de gids, met de stand van elke taak. Hun notities blijven erbuiten
GET /api/v1/admin/export?day=	De export die elke dag om 6:30 uur in Guayaquil wordt geschreven, die van die dag of de nieuwste, met de dagen die er zijn: de acceptaties, de makers en de plaatsen, volledig tot het moment van de run

chain noemt één netwerk dat de implementatie bedient, base-sepolia (of de chain-ID, 84532) of solana-devnet; laat je het weg, dan is het de standaard EVM-chain. since is ISO 8601 of unix-seconden. cursor is de pagination.next_cursor van de vorige pagina, ondoorzichtig, en null op de laatste pagina.

In acceptaties, makers en de export zegt email_basis wat voor e-mailadres een rij draagt. email met founder_tagged_link is bevestigd: het KURV-team heeft de link voor één persoon getagd, hij is één keer gebruikt en één aanvraag draagt de tag. email_claimed met ref_tag_unverified is een bewering en nooit een identiteit: het account kwam via een adres met een ref-tag en één aanvraag draagt die tag, maar iedereen kan zo’n adres typen. Tags van vóór 30 oktober 2026 geven geen van beide, en een in een formulier getypte naam ook niet.

Elk antwoord bevat api_version, chain, environment en read_at. Bedragen zijn basiseenheden als decimale strings, één item per munt onder native; usd is het USDC-deel in dollars, of null als er alleen een munt zonder dollarbedrag is verhandeld. Geld in de ene munt wordt nooit opgeteld bij geld in een andere.

Eén voorbeeld van elk

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 }

Limieten en actualiteit

Elke sleutel mag 120 verzoeken per minuut doen, en 30 per minuut op /api/v1/admin/*. Daarboven is het antwoord 429 met een header retry-after. Elk antwoord is hoogstens 60 seconden oud: de server leest één keer per minuut en read_at is het tijdstip van die lezing. Wil je mints volgen terwijl ze gebeuren, roep dan elke 30 tot 60 seconden /api/v1/stats/mints aan met since op de laatste read_at die je zag; er is geen stream die je open hoeft te houden.

Wat een sleutel niet kan

Niets. Een sleutel leest. Hij kan geen collectie maken, geen lancering voorbereiden, niet minten, niet handelen, geen profiel wijzigen en niet aan een uitnodiging komen. Een agent die collecties moet bouwen, koppelt in plaats daarvan via MCP, met de goedkeuring van de persoon, en die koppeling staat los van elke sleutel.

Fouten gebruiken { "api_version": "1", "error": { "code": "...", "message": "..." } } met de statuscodes 400, 401, 403, 429 of 503. De openbare routes zonder sleutel staan beschreven in Openbare API’s; KURV voor ontwikkelaars noemt elk toegangspunt. De vergoedingen in deze getallen zijn die van elke collectie zelf: lees Kosten en Risico’s en disclaimer.