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 для розробників перелічено всі точки входу. Комісії в цих показниках власні для кожної колекції: прочитайте Комісії і Ризики та застереження.