API данных KURV

API данных отвечает на вопросы, которые агент или дашборд задаёт о KURV: сколько коллекций запущено, что заминчено, что продано, откуда пришли регистрации. Он только читает. Ключ открывает только маршруты GET в /api/v1 и больше ничего: ни один маршрут здесь ничего не создаёт, не меняет, не подписывает и не тратит.

Аутентификация

Каждый запрос несёт API-ключ как bearer-токен:

Authorization: Bearer kurv_sk_...

Ключи создаёт команда KURV, по одному на агента, и показывает один раз при создании. KURV хранит только дайджест, поэтому потерянный ключ заменяют, а не восстанавливают. Ключ можно отозвать в любой момент; его следующий запрос будет отклонён. Запросы без ключа, с отозванным ключом или с ключом, у которого нет области доступа маршрута, получают 401 или 403 с одним предложением, которое это объясняет.

Области доступа

Область	Что открывает
kurv:stats:read	Четыре маршрута /api/v1/stats/*: счётчики, объём, комиссии и источники, без эл. почты и без имён в ответах
kurv:admin:read	/api/v1/admin/*: заявки с их адресами эл. почты, кто принял приглашение, кто стоит за каждой коллекцией, занятые места, ежедневная выгрузка и счётчики по источникам

У ключа одна область доступа или обе. Только административная область даёт адреса эл. почты.

Эндпоинты

Запрос	Что отвечает
GET /api/v1/stats/overview?chain=	Запущенные коллекции, минты, уникальные минтеры, объём, комиссии, авторы и регистрации, каждое за последние 24 часа, последние 7 дней и за всё время
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Каждая запущенная коллекция с total_minted, её объёмом по монетам, последним минтом и аккаунтом автора, по 25 на страницу
GET /api/v1/stats/mints?chain=&since=&cursor=	Минты от новых к старым, по 50 на страницу, начиная с since
GET /api/v1/stats/users?chain=&since=	Регистрации, аккаунты по сетям, активные авторы и минтеры, разбивка по метке источника и воронка от регистрации до запуска
GET /api/v1/admin/signups?since=&source=	Заявки, аккаунты, ссылки-приглашения с их активациями, счётчики по источникам и запуски без метки
GET /api/v1/admin/acceptances?since=&source=	Каждое принятое приглашение, сначала новые: аккаунт, его профиль, его ник в X, адрес эл. почты, если он указан в заявке, время и метка, с которой он пришёл
GET /api/v1/admin/creators?chain=&since=	Кто стоит за каждой коллекцией в каждой сети или в той, что названа в chain: аккаунт, его профиль, его ник и его ник в X, если он известен
GET /api/v1/admin/seats	Занятые на данный момент места, день за днём
GET /api/v1/admin/funnel?chain=&since=	Принятые приглашения в одной сети, по периодам и меткам, и воронка с ними
GET /api/v1/admin/testers	Все, кого впустили, и все, кто отчитался в руководстве, с состоянием каждого задания. Их заметки остаются в стороне
GET /api/v1/admin/export?day=	Выгрузка, которая пишется каждый день в 6:30 утра по Гуаякилю, за этот день или самая новая, со списком дней: принятия, авторы и места, полная на момент запуска

chain называет одну сеть, которую обслуживает развёртывание: base-sepolia (или её chain id, 84532) или solana-devnet; если его не указать, используется EVM-сеть по умолчанию. since задаётся в ISO 8601 или в секундах unix. cursor это pagination.next_cursor предыдущей страницы, непрозрачное значение, на последней странице равное null.

В принятиях, авторах и выгрузке email_basis говорит, какой адрес эл. почты в строке. email с founder_tagged_link подтверждён: команда KURV пометила ссылку для одного человека, ею воспользовались один раз, и одна заявка несёт эту метку. email_claimed с ref_tag_unverified это заявление, а не личность: аккаунт пришёл с адреса с меткой ref, и одна заявка несёт эту метку, но такой адрес может набрать любой. Метки до 30 октября 2026 не дают ни того, ни другого, как и ник, набранный в форме.

Каждый ответ содержит api_version, chain, environment и read_at. Суммы указаны в базовых единицах как десятичные строки, по одной записи на монету в native; usd это часть в USDC в долларах или null, если двигалась только монета без долларовой оценки. Деньги в одной монете никогда не складываются с деньгами в другой.

По одному примеру на каждый

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 }

Лимиты и свежесть

Каждый ключ может делать 120 запросов в минуту, а к /api/v1/admin/* 30 в минуту. Сверх этого ответ будет 429 с заголовком retry-after. Каждый ответ не старше 60 секунд: сервер читает данные раз в минуту, а read_at это время этого чтения. Чтобы следить за минтами по мере их появления, вызывайте /api/v1/stats/mints с интервалом от 30 до 60 секунд с since, равным последнему увиденному read_at; держать открытым поток не нужно.

Чего ключ не может

Ничего. Ключ только читает. Он не может создать коллекцию, подготовить запуск, минтить, торговать, менять профиль или трогать приглашение. Агент, который должен собирать коллекции, подключается вместо этого через MCP, с одобрения человека, и это подключение не связано ни с каким ключом.

Ошибки имеют вид { "api_version": "1", "error": { "code": "...", "message": "..." } } с кодами статуса 400, 401, 403, 429 или 503. Публичные маршруты без ключа описаны на странице Публичные API; все точки входа перечислены на странице KURV для разработчиков. Комиссии в этих цифрах у каждой коллекции свои: прочитайте Комиссии и Риски и отказ от ответственности.