API danych KURV

API danych odpowiada na pytania, które agent albo panel zadaje o KURV: ile kolekcji wypuszczono, co zmintowano, co się ruszyło, skąd przyszły rejestracje. Działa tylko do odczytu. Klucz otwiera tylko trasy GET pod /api/v1 i nic więcej: żadna trasa tutaj niczego nie tworzy, nie zmienia, nie podpisuje ani nie wydaje.

Uwierzytelnianie

Każde żądanie przesyła klucz API jako token typu bearer:

Authorization: Bearer kurv_sk_...

Klucze tworzy zespół KURV, jeden na agenta, i pokazuje je tylko raz, przy utworzeniu. KURV przechowuje tylko skrót, więc zgubiony klucz jest zastępowany nowym, a nie odzyskiwany. Klucz można w każdej chwili unieważnić; jego następne żądanie zostanie odrzucone. Żądania bez klucza, z unieważnionym kluczem albo z kluczem bez zakresu danej trasy dostają 401 lub 403 z jednym zdaniem, które to wyjaśnia.

Zakresy

Zakres	Otwiera
kurv:stats:read	Cztery trasy /api/v1/stats/*: liczby, wolumen, opłaty i źródła, bez e-maili i bez nazwisk w żadnej odpowiedzi
kurv:admin:read	/api/v1/admin/*: zgłoszenia z e-mailami, kto przyjął zaproszenie, osoba stojąca za każdą kolekcją, zajęte miejsca, codzienny eksport oraz liczby według źródła

Klucz ma jeden zakres albo oba. Zakres administracyjny jako jedyny zawiera e-maile.

Punkty dostępu

Żądanie	Odpowiada
GET /api/v1/stats/overview?chain=	Wypuszczone kolekcje, minty, unikalni mintujący, wolumen, opłaty, twórcy i rejestracje, każde za ostatnie 24 godziny, ostatnie 7 dni i cały czas
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Każda wypuszczona kolekcja z total_minted, jej wolumenem według monety, ostatnim mintem i kontem twórcy, 25 na stronę
GET /api/v1/stats/mints?chain=&since=&cursor=	Minty od najnowszych, 50 na stronę, od since wzwyż
GET /api/v1/stats/users?chain=&since=	Rejestracje, konta w każdej sieci, aktywni twórcy i mintujący, podział według tagu źródła i lejek od rejestracji do wypuszczenia
GET /api/v1/admin/signups?since=&source=	Zgłoszenia, konta, linki z zaproszeniami z ich aktywacjami, liczby według źródła i wypuszczenia bez tagu
GET /api/v1/admin/acceptances?since=&source=	Każde przyjęte zaproszenie, najnowsze najpierw: konto, jego profil, jego nazwa w X, e-mail, jeśli podaje go zgłoszenie, czas i tag, z którym przyszło
GET /api/v1/admin/creators?chain=&since=	Osoba stojąca za każdą kolekcją w każdej sieci albo w tej, którą wskazuje chain: konto, jego profil, jego nazwa i jego nazwa w X, jeśli jest znana
GET /api/v1/admin/seats	Dotąd zajęte miejsca, dzień po dniu
GET /api/v1/admin/funnel?chain=&since=	Przyjęte zaproszenia w jednej sieci, według okresu i tagu, wraz z lejkiem
GET /api/v1/admin/testers	Wszyscy wpuszczeni i wszyscy, którzy zgłosili wynik w przewodniku, ze stanem każdego zadania. Ich notatki zostają poza tym
GET /api/v1/admin/export?day=	Eksport zapisywany codziennie o 6:30 rano w Guayaquil, z danego dnia albo najnowszy, wraz z dostępnymi dniami: przyjęcia, twórcy i miejsca, kompletny do chwili uruchomienia

chain wskazuje jedną sieć obsługiwaną przez wdrożenie, base-sepolia (albo jej chain id, 84532) lub solana-devnet; gdy go pominiesz, używana jest domyślna sieć EVM. since to ISO 8601 albo sekundy uniksowe. cursor to pagination.next_cursor poprzedniej strony, nieprzejrzysty, a na ostatniej stronie null.

W przyjęciach, twórcach i eksporcie email_basis mówi, jaki rodzaj e-maila ma wiersz. email z founder_tagged_link jest potwierdzony: zespół KURV oznaczył link dla jednej osoby, użyto go raz i jedno zgłoszenie ma ten tag. email_claimed z ref_tag_unverified to deklaracja, nigdy tożsamość: konto przyszło z adresu z tagiem ref i jedno zgłoszenie ma ten tag, ale taki adres może wpisać każdy. Tagi sprzed 30 października 2026 nie dają żadnego z nich, podobnie jak nazwa wpisana w formularzu.

Każda odpowiedź zawiera api_version, chain, environment i read_at. Kwoty są w jednostkach bazowych jako dziesiętne ciągi znaków, po jednym wpisie na monetę pod native; usd to część w USDC wyrażona w dolarach albo null, gdy ruszyła się tylko moneta bez wartości w dolarach. Pieniądze w jednej monecie nigdy nie są dodawane do pieniędzy w innej.

Po jednym przykładzie

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 }

Limity i aktualność

Każdy klucz może wysłać 120 żądań na minutę, a do /api/v1/admin/* 30 na minutę. Powyżej tego odpowiedzią jest 429 z nagłówkiem retry-after. Każda odpowiedź ma najwyżej 60 sekund: serwer odczytuje dane raz na minutę, a read_at to czas tego odczytu. Aby śledzić minty na bieżąco, wywołuj /api/v1/stats/mints co 30 do 60 sekund z since ustawionym na ostatnie read_at, jakie widzisz; nie ma strumienia, który trzeba trzymać otwarty.

Czego klucz nie może

Niczego. Klucz odczytuje. Nie może utworzyć kolekcji, przygotować wypuszczenia, mintować, handlować, zmieniać profilu ani dotykać zaproszeń. Agent, który ma budować kolekcje, łączy się zamiast tego przez MCP, za zgodą danej osoby, a to połączenie jest niezależne od jakiegokolwiek klucza.

Błędy mają postać { "api_version": "1", "error": { "code": "...", "message": "..." } } z kodami statusu 400, 401, 403, 429 lub 503. Publiczne trasy bez klucza opisuje strona Publiczne API; wszystkie punkty wejścia wymienia strona KURV dla programistów. Opłaty w tych wartościach to opłaty każdej kolekcji: przeczytaj Opłaty i Ryzyka i zastrzeżenia.