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 cadastros. Ela é somente de leitura. Uma chave abre apenas as rotas GET em /api/v1 e mais nada: nenhuma rota aqui cria, altera, assina ou gasta coisa alguma.

Autenticação

Toda requisição leva uma chave de API como token bearer:

Authorization: Bearer kurv_sk_...

As chaves são criadas pela equipe do KURV, uma por agente, e mostradas uma única vez, quando são criadas. O KURV guarda só um resumo criptográfico, então uma chave perdida é substituída, nunca recuperada. Uma chave pode ser revogada a qualquer momento; a próxima requisição dela é recusada. Requisições sem chave, com uma chave revogada ou com uma chave que não tem o escopo da rota recebem um 401 ou 403 com uma frase que diz isso.

Escopos

Escopo	Abre
kurv:stats:read	As quatro rotas /api/v1/stats/*: contagens, volume, taxas e origens, sem nenhum e-mail e nenhum nome em nenhuma resposta
kurv:admin:read	/api/v1/admin/*: as inscrições com os 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 escopo ou os dois. O escopo de admin é o único que traz e-mails.

Endpoints

Requisição	Responde
GET /api/v1/stats/overview?chain=	Coleções lançadas, cunhagens, pessoas únicas que cunharam, volume, taxas, criadores e cadastros, cada um nas últimas 24 horas, nos últimos 7 dias e desde o início
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 das mais recentes para as mais antigas, 50 por página, a partir de since
GET /api/v1/stats/users?chain=&since=	Cadastros, contas por rede, criadores e pessoas que cunharam ativos, o detalhamento por tag de origem e o funil do cadastro ao lançamento
GET /api/v1/admin/signups?since=&source=	Inscrições, contas, links de convite com os resgates, contagens por origem e lançamentos que não traziam nenhuma tag
GET /api/v1/admin/acceptances?since=&source=	Cada convite aceito, o mais recente primeiro: a conta, o perfil, o usuário no X, um e-mail quando uma inscrição indica um, a hora e a tag 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 nome de usuário e o usuário 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 aceitos em uma rede, por período e por tag, e o funil com eles
GET /api/v1/admin/testers	Todos que entraram e todos que relataram no guia, com a situação de cada tarefa. As anotações ficam de fora
GET /api/v1/admin/export?day=	A exportação escrita todo dia às 6:30 em Guayaquil, a daquele dia ou a mais recente, com os dias que existem: os aceites, quem cria e as vagas, completa até o momento em que rodou

chain indica uma rede que a implantação atende, base-sepolia (ou o chain id dela, 84532) ou solana-devnet; se for omitido, vale a rede EVM padrão. since é ISO 8601 ou segundos unix. cursor é o pagination.next_cursor da página anterior, opaco, e é null na última página.

Nos aceites, em quem cria e na exportação, email_basis diz que tipo de e-mail uma linha traz. email com founder_tagged_link é verificado: a equipe do KURV marcou o link para uma pessoa, ele foi usado uma vez e uma inscrição traz a tag. email_claimed com ref_tag_unverified é uma afirmação, nunca uma identidade: a conta chegou de um endereço com uma tag ref e uma inscrição traz essa tag, mas qualquer um pode digitar esse endereço. Tags anteriores a 30 de outubro de 2026 não dão nenhum dos dois, nem um usuário digitado em um formulário.

Toda resposta traz api_version, chain, environment e read_at. Os valores são unidades base em strings 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ólar. Dinheiro em uma moeda nunca é somado a dinheiro em outra.

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 atualização

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

O que uma chave não pode fazer

Nada. Uma chave lê. Ela não pode criar uma coleção, preparar um lançamento, cunhar, negociar, mudar um perfil nem mexer em um convite. Um agente que deve criar coleções se conecta pelo MCP, com a aprovação da pessoa, e essa conexão é separada de qualquer chave.

Os erros usam { "api_version": "1", "error": { "code": "...", "message": "..." } } com os códigos de status 400, 401, 403, 429 ou 503. As rotas públicas, sem chave, estão descritas em APIs públicas; KURV para desenvolvedores lista todos os pontos de entrada. As taxas nesses números são as de cada coleção: leia Taxas e Riscos e isenção de responsabilidade.