KURV डेटा API

डेटा API उन सवालों का जवाब देता है जो कोई एजेंट या डैशबोर्ड KURV के बारे में पूछता है: कितने कलेक्शन लॉन्च हुए, क्या मिंट हुआ, क्या-क्या चला, साइन-अप कहाँ से आए। यह सिर्फ़ पढ़ने के लिए है। एक कुंजी /api/v1 के नीचे सिर्फ़ GET रूट खोलती है और कुछ नहीं: यहाँ का कोई रूट कुछ बनाता, बदलता, साइन करता या खर्च नहीं करता।

प्रमाणीकरण

हर अनुरोध API कुंजी को बेयरर टोकन की तरह साथ ले जाता है:

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 (या उसकी चेन आईडी 84532) या solana-devnet; छोड़ देने पर यह डिफ़ॉल्ट EVM चेन है। since ISO 8601 या unix सेकंड है। cursor पिछले पेज का pagination.next_cursor है, अपारदर्शी, और आख़िरी पेज पर null।

स्वीकृतियों, क्रिएटरों और एक्सपोर्ट में email_basis बताता है कि पंक्ति में किस तरह का ईमेल है। founder_tagged_link के साथ email सत्यापित है: KURV टीम ने लिंक एक व्यक्ति के लिए टैग किया, वह एक बार इस्तेमाल हुआ, और एक आवेदन में वह टैग है। ref_tag_unverified के साथ email_claimed एक दावा है, पहचान कभी नहीं: खाता 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 for Developers हर प्रवेश बिंदु की सूची देता है। इन आँकड़ों में शुल्क हर कलेक्शन के अपने हैं: शुल्क और जोखिम और अस्वीकरण पढ़ें।