API data KURV

API data menjawab pertanyaan yang diajukan agen atau dasbor tentang KURV: berapa koleksi yang diluncurkan, apa yang di-mint, apa yang berpindah, dari mana pendaftaran datang. API ini hanya baca. Sebuah kunci hanya membuka rute GET di bawah /api/v1 dan tidak ada yang lain: tidak ada rute di sini yang membuat, mengubah, menandatangani, atau membelanjakan apa pun.

Autentikasi

Setiap permintaan membawa kunci API sebagai token bearer:

Authorization: Bearer kurv_sk_...

Kunci dibuat oleh tim KURV, satu per agen, dan ditampilkan sekali saat dibuat. KURV hanya menyimpan digest-nya, jadi kunci yang hilang diganti, bukan dipulihkan. Kunci dapat dicabut kapan saja; permintaan berikutnya ditolak. Permintaan tanpa kunci, dengan kunci yang sudah dicabut, atau dengan kunci yang tidak punya cakupan rute tersebut mendapat 401 atau 403 dengan satu kalimat yang menjelaskannya.

Cakupan

Cakupan	Membuka
kurv:stats:read	Empat rute /api/v1/stats/*: jumlah, volume, biaya, dan sumber, tanpa email dan nama di jawaban mana pun
kurv:admin:read	/api/v1/admin/*: lamaran beserta emailnya, siapa yang menerima undangan, siapa di balik setiap koleksi, kursi yang terpakai, ekspor harian, dan jumlah per sumber

Sebuah kunci membawa satu cakupan atau keduanya. Cakupan admin adalah satu-satunya yang membawa email.

Endpoint

Permintaan	Jawaban
GET /api/v1/stats/overview?chain=	Koleksi yang diluncurkan, mint, minter unik, volume, biaya, kreator, dan pendaftaran, masing-masing untuk 24 jam terakhir, 7 hari terakhir, dan sepanjang waktu
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Setiap koleksi yang diluncurkan dengan total_minted, volume per koin, mint terakhir, dan akun kreatornya, 25 per halaman
GET /api/v1/stats/mints?chain=&since=&cursor=	Mint dari yang terbaru, 50 per halaman, sejak since
GET /api/v1/stats/users?chain=&since=	Pendaftaran, akun per jaringan, kreator dan minter aktif, rincian per tag sumber, dan corong dari pendaftaran hingga peluncuran
GET /api/v1/admin/signups?since=&source=	Lamaran, akun, tautan undangan beserta penukarannya, jumlah per sumber, dan peluncuran tanpa tag
GET /api/v1/admin/acceptances?since=&source=	Setiap undangan yang diterima, yang terbaru dulu: akun, profilnya, handle X-nya, email jika lamaran menyebutkannya, waktu dan tag saat datang
GET /api/v1/admin/creators?chain=&since=	Siapa di balik setiap koleksi di setiap jaringan, atau di jaringan yang disebut chain: akun, profilnya, handle-nya, dan handle X-nya bila diketahui
GET /api/v1/admin/seats	Kursi yang terpakai sejauh ini, hari demi hari
GET /api/v1/admin/funnel?chain=&since=	Undangan yang diterima di satu jaringan, per periode dan per tag, beserta corongnya
GET /api/v1/admin/testers	Semua yang sudah masuk dan semua yang melapor di panduan, dengan status tiap tugas. Catatan mereka tidak disertakan
GET /api/v1/admin/export?day=	Ekspor yang ditulis setiap hari pukul 6:30 pagi di Guayaquil, milik hari itu atau yang terbaru, beserta hari yang ada: penerimaan, kreator, dan kursi, lengkap sampai saat dijalankan

chain menyebut satu jaringan yang dilayani deployment ini, base-sepolia (atau ID rantainya, 84532) atau solana-devnet; jika dikosongkan, rantai EVM bawaan yang dipakai. since berupa ISO 8601 atau detik unix. cursor adalah pagination.next_cursor dari halaman sebelumnya, buram, dan null di halaman terakhir.

Di penerimaan, kreator, dan ekspor, email_basis menyebut jenis email yang dibawa sebuah baris. email dengan founder_tagged_link sudah terverifikasi: tim KURV menandai tautan untuk satu orang, tautan dipakai sekali, dan satu lamaran membawa tag itu. email_claimed dengan ref_tag_unverified adalah klaim dan bukan identitas: akun datang dari alamat dengan tag ref dan satu lamaran membawa tag itu, tetapi siapa pun bisa mengetik alamat seperti itu. Tag sebelum 30 Oktober 2026 tidak memberikan keduanya, begitu pula handle yang diketik di formulir.

Setiap jawaban membawa api_version, chain, environment, dan read_at. Jumlah adalah string desimal dalam satuan terkecil, satu entri per koin di bawah native; usd adalah bagian USDC dalam dolar, atau null ketika hanya koin tanpa nilai dolar yang berpindah. Uang dalam satu koin tidak pernah dijumlahkan dengan uang dalam koin lain.

Satu contoh untuk masing-masing

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 }

Batas dan kesegaran

Setiap kunci boleh mengirim 120 permintaan per menit, dan 30 per menit di /api/v1/admin/*. Lewat dari itu, jawabannya 429 dengan header retry-after. Setiap jawaban paling lama berumur 60 detik: server membaca sekali per menit dan read_at adalah waktu pembacaan itu. Untuk mengikuti mint saat terjadi, panggil /api/v1/stats/mints setiap 30 sampai 60 detik dengan since diisi read_at terakhir yang Anda lihat; tidak ada stream yang perlu dibiarkan terbuka.

Apa yang tidak bisa dilakukan kunci

Tidak ada. Kunci hanya membaca. Ia tidak bisa membuat koleksi, menyiapkan peluncuran, mint, berdagang, mengubah profil, atau menyentuh undangan. Agen yang seharusnya membangun koleksi terhubung lewat MCP dengan persetujuan orangnya, dan koneksi itu terpisah dari kunci mana pun.

Kesalahan memakai { "api_version": "1", "error": { "code": "...", "message": "..." } } dengan kode status 400, 401, 403, 429, atau 503. Rute publik tanpa kunci dijelaskan di API publik; KURV for Developers mencantumkan setiap titik masuk. Biaya dalam angka-angka ini adalah biaya masing-masing koleksi: baca Biaya dan Risiko dan penafian.