API dữ liệu KURV

API dữ liệu trả lời những câu hỏi mà một agent hay một bảng điều khiển đặt ra về KURV: bao nhiêu bộ sưu tập đã ra mắt, những gì đã được mint, dòng tiền nào đã chuyển, đăng ký đến từ đâu. Nó chỉ đọc. Một khóa chỉ mở các tuyến GET dưới /api/v1 và không gì khác: không tuyến nào ở đây tạo, thay đổi, ký hay chi tiêu bất cứ thứ gì.

Xác thực

Mọi yêu cầu mang khóa API dưới dạng bearer token:

Authorization: Bearer kurv_sk_...

Khóa do đội KURV tạo, mỗi agent một khóa, và chỉ hiển thị một lần khi tạo. KURV chỉ giữ bản tóm lược, nên khóa bị mất sẽ được thay mới, không khôi phục. Khóa có thể bị thu hồi bất cứ lúc nào; yêu cầu kế tiếp của nó bị từ chối. Yêu cầu không có khóa, dùng khóa đã thu hồi, hoặc khóa thiếu phạm vi của tuyến sẽ nhận 401 hoặc 403 kèm một câu nói rõ lý do.

Phạm vi

Phạm vi	Mở ra
kurv:stats:read	Bốn tuyến /api/v1/stats/*: số lượng, khối lượng, phí và nguồn, không có email hay tên trong bất kỳ câu trả lời nào
kurv:admin:read	/api/v1/admin/*: đơn đăng ký kèm email, ai đã chấp nhận lời mời, người đứng sau mỗi bộ sưu tập, số suất đã dùng, bản xuất hằng ngày và số lượng theo nguồn

Một khóa mang một phạm vi hoặc cả hai. Phạm vi admin là phạm vi duy nhất mang email.

Điểm cuối

Yêu cầu	Trả lời
GET /api/v1/stats/overview?chain=	Bộ sưu tập đã ra mắt, lượt mint, người mint riêng biệt, khối lượng, phí, nhà sáng tạo và lượt đăng ký, mỗi mục cho 24 giờ qua, 7 ngày qua và toàn bộ thời gian
GET /api/v1/stats/collections?chain=&sort=volume|mints|new&cursor=	Mọi bộ sưu tập đã ra mắt với total_minted, khối lượng theo đồng, lượt mint gần nhất và tài khoản nhà sáng tạo, 25 mỗi trang
GET /api/v1/stats/mints?chain=&since=&cursor=	Lượt mint mới nhất trước, 50 mỗi trang, từ since trở đi
GET /api/v1/stats/users?chain=&since=	Lượt đăng ký, tài khoản theo mạng, nhà sáng tạo và người mint đang hoạt động, phân tích theo thẻ nguồn, và phễu từ đăng ký đến ra mắt
GET /api/v1/admin/signups?since=&source=	Đơn đăng ký, tài khoản, liên kết mời kèm lượt đổi, số lượng theo nguồn, và các lần ra mắt không mang thẻ
GET /api/v1/admin/acceptances?since=&source=	Mọi lời mời đã được chấp nhận, mới nhất trước: tài khoản, hồ sơ, tên X, email nếu đơn đăng ký có ghi, thời gian và thẻ đi kèm khi đến
GET /api/v1/admin/creators?chain=&since=	Người đứng sau mỗi bộ sưu tập trên mọi mạng, hoặc trên mạng mà chain chỉ ra: tài khoản, hồ sơ, tên người dùng và tên X nếu biết
GET /api/v1/admin/seats	Số suất đã dùng đến nay, theo từng ngày
GET /api/v1/admin/funnel?chain=&since=	Lời mời đã chấp nhận trên một mạng, theo giai đoạn và theo thẻ, cùng phễu
GET /api/v1/admin/testers	Mọi người đã vào và mọi người đã báo cáo trong hướng dẫn, kèm trạng thái từng nhiệm vụ. Ghi chú của họ không có ở đây
GET /api/v1/admin/export?day=	Bản xuất được ghi mỗi ngày lúc 6:30 sáng ở Guayaquil, của ngày đó hoặc mới nhất, cùng các ngày hiện có: lượt chấp nhận, người tạo và suất, đầy đủ đến thời điểm chạy

chain gọi tên một mạng mà bản triển khai này phục vụ, base-sepolia (hoặc id chuỗi của nó, 84532) hay solana-devnet; bỏ trống thì là chuỗi EVM mặc định. since là ISO 8601 hoặc giây unix. cursor là pagination.next_cursor của trang trước, không đọc được, và là null ở trang cuối.

Trong lượt chấp nhận, người tạo và bản xuất, email_basis cho biết một dòng mang loại email nào. email với founder_tagged_link đã được xác minh: đội KURV gắn thẻ liên kết cho một người, liên kết được dùng một lần và một đơn đăng ký mang thẻ đó. email_claimed với ref_tag_unverified là lời tự nhận, không bao giờ là danh tính: tài khoản đến từ địa chỉ có thẻ ref và một đơn đăng ký mang thẻ đó, nhưng ai cũng có thể gõ địa chỉ như vậy. Thẻ trước ngày 30 tháng 10 năm 2026 không cho loại nào, tên gõ vào biểu mẫu cũng vậy.

Mọi câu trả lời mang api_version, chain, environment và read_at. Số tiền là chuỗi thập phân theo đơn vị nhỏ nhất, mỗi đồng một mục dưới native; usd là phần USDC tính bằng đô la, hoặc null khi chỉ có đồng không có giá đô la chuyển động. Tiền ở một đồng không bao giờ được cộng với tiền ở đồng khác.

Mỗi tuyến một ví dụ

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 }

Giới hạn và độ mới

Mỗi khóa được gửi 120 yêu cầu một phút, và 30 một phút trên /api/v1/admin/*. Quá mức đó, câu trả lời là 429 kèm tiêu đề retry-after. Mọi câu trả lời cũ nhất là 60 giây: máy chủ đọc mỗi phút một lần và read_at là thời điểm của lần đọc đó. Để theo dõi lượt mint khi chúng diễn ra, gọi /api/v1/stats/mints mỗi 30 đến 60 giây với since đặt bằng read_at cuối cùng bạn thấy; không có luồng nào cần giữ mở.

Khóa không làm được gì

Không gì cả. Khóa chỉ đọc. Nó không thể tạo bộ sưu tập, chuẩn bị ra mắt, mint, giao dịch, đổi hồ sơ hay chạm vào lời mời. Agent cần xây bộ sưu tập thì kết nối qua MCP với sự chấp thuận của người dùng, và kết nối đó tách biệt với mọi khóa.

Lỗi dùng { "api_version": "1", "error": { "code": "...", "message": "..." } } với mã trạng thái 400, 401, 403, 429 hoặc 503. Các tuyến công khai không cần khóa được mô tả trong API công khai; KURV for Developers liệt kê mọi điểm vào. Phí trong các số liệu này là phí riêng của từng bộ sưu tập: hãy đọc Phí và Rủi ro và tuyên bố miễn trừ.