API de dados do KURV

A API de dados responde às perguntas que um agente ou um painel faz sobre o KURV: quantas coleções foram lançadas, o que foi cunhado, o que se movimentou, de onde vieram os registos. É só de leitura. Uma chave abre apenas as rotas GET em /api/v1 e mais nada: nenhuma rota aqui cria, altera, assina ou gasta o que quer que seja.

Autenticação

Cada pedido leva uma chave de API como bearer token:

Authorization: Bearer kurv_sk_...

As chaves são criadas pela equipa do KURV, uma por agente, e mostradas uma única vez quando são criadas. O KURV guarda apenas um resumo, por isso uma chave perdida é substituída, nunca recuperada. Uma chave pode ser revogada a qualquer momento; o pedido seguinte é recusado. Os pedidos sem chave, com uma chave revogada ou com uma chave que não tem o âmbito da rota recebem um 401 ou um 403, com uma frase que o explica.

Âmbitos

Âmbito	Abre
kurv:stats:read	As quatro rotas /api/v1/stats/*: contagens, volume, comissões e origens, sem e-mails nem nomes em nenhuma resposta
kurv:admin:read	/api/v1/admin/*: candidaturas com os respetivos e-mails, quem aceitou um convite, quem está por trás de cada coleção, as vagas usadas, a exportação diária e as contagens por origem

Uma chave tem um âmbito ou os dois. O âmbito de administração é o único que inclui e-mails.

Endpoints

Pedido	Responde com
GET /api/v1/stats/overview?chain=	Coleções lançadas, cunhagens, cunhadores únicos, volume, comissões, criadores e registos, cada um para as últimas 24 horas, os últimos 7 dias e desde sempre
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Todas as coleções lançadas, com total_minted, o volume por moeda, a última cunhagem e a conta do criador, 25 por página
GET /api/v1/stats/mints?chain=&since=&cursor=	Cunhagens, da mais recente para a mais antiga, 50 por página, a partir de since
GET /api/v1/stats/users?chain=&since=	Registos, contas por rede, criadores e cunhadores ativos, a divisão por etiqueta de origem e o funil do registo ao lançamento
GET /api/v1/admin/signups?since=&source=	Candidaturas, contas, ligações de convite com os respetivos resgates, contagens por origem e lançamentos sem etiqueta
GET /api/v1/admin/acceptances?since=&source=	Cada convite aceite, o mais recente primeiro: a conta, o perfil, o identificador no X, um e-mail quando uma candidatura o indica, a hora e a etiqueta com que chegou
GET /api/v1/admin/creators?chain=&since=	Quem está por trás de cada coleção em cada rede, ou na que chain indica: a conta, o perfil, o identificador e o identificador no X quando é conhecido
GET /api/v1/admin/seats	As vagas usadas até agora, dia a dia
GET /api/v1/admin/funnel?chain=&since=	Os convites aceites numa rede, por período e por etiqueta, e o funil com eles
GET /api/v1/admin/testers	Todos os que entraram e os que reportaram no guia, com o estado de cada tarefa. As notas ficam de fora
GET /api/v1/admin/export?day=	A exportação escrita todos os dias às 6:30 em Guayaquil, a desse dia ou a mais recente, com os dias que existem: as aceitações, quem cria e as vagas, completa até ao momento em que correu

chain indica uma rede servida pela implementação, base-sepolia (ou o respetivo chain id, 84532) ou solana-devnet; se for omitido, é a cadeia EVM predefinida. since é ISO 8601 ou segundos unix. cursor é o pagination.next_cursor da página anterior, opaco, e é null na última página.

Nas aceitações, em quem cria e na exportação, email_basis indica que tipo de e-mail uma linha traz. email com founder_tagged_link está verificado: a equipa do KURV etiquetou a ligação para uma pessoa, foi usada uma vez e uma candidatura traz a etiqueta. email_claimed com ref_tag_unverified é uma afirmação, nunca uma identidade: a conta chegou de um endereço com uma etiqueta ref e uma candidatura traz essa etiqueta, mas qualquer pessoa pode escrever esse endereço. Etiquetas anteriores a 30 de outubro de 2026 não dão nenhum dos dois, nem um identificador escrito num formulário.

Todas as respostas trazem api_version, chain, environment e read_at. Os montantes são unidades base em cadeias de texto decimais, uma entrada por moeda em native; usd é a parte em USDC, em dólares, ou null quando só se movimentou uma moeda sem valor em dólares. O dinheiro numa moeda nunca é somado ao dinheiro noutra.

Um exemplo de cada

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 e atualidade

Cada chave pode fazer 120 pedidos por minuto, e 30 por minuto em /api/v1/admin/*. Acima disso, a resposta é 429 com um cabeçalho retry-after. Cada resposta tem no máximo 60 segundos: o servidor lê uma vez por minuto e read_at é a hora dessa leitura. Para acompanhar as cunhagens à medida que acontecem, chame /api/v1/stats/mints a cada 30 a 60 segundos com since definido como o último read_at que viu; não há nenhum stream para manter aberto.

O que uma chave não pode fazer

Nada. Uma chave lê. Não pode criar uma coleção, preparar um lançamento, cunhar, negociar, alterar um perfil nem mexer num convite. Um agente que deva criar coleções liga-se antes através do MCP, com a aprovação da pessoa, e essa ligação é independente de qualquer chave.

Os erros usam { "api_version": "1", "error": { "code": "...", "message": "..." } } com os códigos de estado 400, 401, 403, 429 ou 503. As rotas públicas, sem chave, estão descritas em APIs públicas; KURV para programadores lista todos os pontos de entrada. As comissões nestes números são as de cada coleção: leia Comissões e Riscos e aviso legal.