API de datos de KURV

La API de datos responde a las preguntas que un agente o un panel se hacen sobre KURV: cuántas colecciones se lanzaron, qué se acuñó, qué se movió, de dónde llegaron los registros. Es de solo lectura. Una clave abre solo las rutas GET bajo /api/v1 y nada más: ninguna ruta de aquí crea, cambia, firma ni gasta nada.

Autenticación

Cada solicitud lleva una clave de API como token bearer:

Authorization: Bearer kurv_sk_...

Las claves las crea el equipo de KURV, una por agente, y se muestran una sola vez, cuando se crean. KURV solo guarda un resumen, así que una clave perdida se sustituye, nunca se recupera. Una clave se puede revocar en cualquier momento; su siguiente solicitud se rechaza. Las solicitudes sin clave, con una clave revocada o con una clave que no tiene el ámbito de la ruta reciben un 401 o un 403 con una frase que lo dice.

Ámbitos

Ámbito	Abre
kurv:stats:read	Las cuatro rutas /api/v1/stats/*: recuentos, volumen, comisiones y orígenes, sin ningún correo ni ningún nombre en ninguna respuesta
kurv:admin:read	/api/v1/admin/*: las solicitudes con sus correos, quién aceptó una invitación, quien está detrás de cada colección, las plazas usadas, la exportación diaria y los recuentos por origen

Una clave lleva un ámbito o los dos. El ámbito de administración es el único que lleva correos.

Endpoints

Solicitud	Responde
GET /api/v1/stats/overview?chain=	Colecciones lanzadas, acuñaciones, acuñadores únicos, volumen, comisiones, creadores y registros, cada uno para las últimas 24 horas, los últimos 7 días y desde siempre
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Cada colección lanzada con total_minted, su volumen por moneda, su última acuñación y la cuenta de su creador, 25 por página
GET /api/v1/stats/mints?chain=&since=&cursor=	Las acuñaciones, de la más reciente a la más antigua, 50 por página, desde since
GET /api/v1/stats/users?chain=&since=	Registros, cuentas por red, creadores y acuñadores activos, el desglose por etiqueta de origen y el embudo desde el registro hasta el lanzamiento
GET /api/v1/admin/signups?since=&source=	Solicitudes, cuentas, enlaces de invitación con sus canjes, recuentos por origen y lanzamientos que no llevaban etiqueta
GET /api/v1/admin/acceptances?since=&source=	Cada invitación aceptada, la más reciente primero: la cuenta, su perfil, su usuario de X, un correo cuando una solicitud lo indica, la hora y la etiqueta con la que llegó
GET /api/v1/admin/creators?chain=&since=	Quien está detrás de cada colección en cada red, o en la que indica chain: la cuenta, su perfil, su nombre de usuario y su usuario de X cuando se conoce
GET /api/v1/admin/seats	Las plazas usadas hasta ahora, día a día
GET /api/v1/admin/funnel?chain=&since=	Las invitaciones aceptadas en una red, por periodo y por etiqueta, y el embudo con ellas
GET /api/v1/admin/testers	Todos los que entraron y todos los que informaron en la guía de pruebas, con el estado de cada tarea. Sus notas quedan fuera
GET /api/v1/admin/export?day=	La exportación que se escribe cada día a las 6:30 AM en Guayaquil, la de ese día o la más reciente, con los días que hay: las aceptaciones, quienes crean y las plazas, completa hasta el momento en que se ejecutó

chain nombra una red que sirve el despliegue, base-sepolia (o su chain id, 84532) o solana-devnet; si se omite, es la cadena EVM por defecto. since va en ISO 8601 o en segundos unix. cursor es el pagination.next_cursor de la página anterior, opaco, y null en la última página.

En las aceptaciones, quienes crean y la exportación, email_basis dice qué clase de correo lleva una fila. email con founder_tagged_link está verificado: el equipo de KURV etiquetó el enlace para una persona, se usó una vez y una solicitud lleva la etiqueta. email_claimed con ref_tag_unverified es una afirmación y nunca una identidad: la cuenta llegó desde una dirección con una etiqueta ref y una solicitud lleva esa etiqueta, pero cualquiera puede escribir esa dirección. Las etiquetas anteriores al 30 de octubre de 2026 no dan ninguno, ni tampoco un usuario escrito en un formulario.

Cada respuesta lleva api_version, chain, environment y read_at. Los importes van en unidades base como cadenas decimales, una entrada por moneda bajo native; usd es la parte en USDC expresada en dólares, o null cuando solo se ha movido una moneda sin cifra en dólares. El dinero en una moneda nunca se suma al dinero en otra.

Un ejemplo de cada una

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 }

Límites y actualización

Cada clave puede hacer 120 solicitudes por minuto, y 30 por minuto en /api/v1/admin/*. Por encima de eso, la respuesta es 429 con una cabecera retry-after. Ninguna respuesta tiene más de 60 segundos: el servidor lee una vez por minuto y read_at es la hora de esa lectura. Para seguir las acuñaciones a medida que ocurren, llama a /api/v1/stats/mints cada 30 a 60 segundos con since en el último read_at que hayas visto; no hay ningún flujo que mantener abierto.

Lo que no puede hacer una clave

Nada. Una clave lee. No puede crear una colección, preparar un lanzamiento, acuñar, intercambiar, cambiar un perfil ni tocar una invitación. Un agente que deba construir colecciones se conecta en su lugar a través de MCP, con la aprobación de la persona, y esa conexión es independiente de cualquier clave.

Los errores usan { "api_version": "1", "error": { "code": "...", "message": "..." } } con los códigos de estado 400, 401, 403, 429 o 503. Las rutas públicas, sin clave, se describen en API públicas; KURV para desarrolladores enumera todos los puntos de entrada. Las comisiones de estas cifras son las propias de cada colección: lee Comisiones y Riesgos y aviso legal.