واجهة بيانات KURV

تجيب واجهة البيانات عن الأسئلة التي يطرحها وكيل أو لوحة بيانات عن KURV: كم مجموعة أُطلقت، وما الذي سُكّ، وما الذي تحرّك، ومن أين جاءت التسجيلات. وهي للقراءة فقط. يفتح المفتاح مسارات GET فقط تحت /api/v1 ولا شيء غيرها: فلا مسار هنا ينشئ أو يغيّر أو يوقّع أو ينفق أي شيء.

المصادقة

يحمل كل طلب مفتاح API كرمز حامل (bearer token):

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 نوع البريد الإلكتروني في الصف. 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 طلبًا في الدقيقة، و30 في الدقيقة على /api/v1/admin/*. وبعد ذلك تكون الإجابة 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 للمطوّرين كل نقاط الدخول. والرسوم في هذه الأرقام خاصة بكل مجموعة: التفاصيل في الرسوم والمخاطر وإخلاء المسؤولية.