KURV 데이터 API

데이터 API는 에이전트나 대시보드가 KURV에 대해 묻는 질문에 답합니다. 몇 개의 컬렉션이 런칭됐는지, 무엇이 민팅됐는지, 무엇이 움직였는지, 가입이 어디에서 왔는지. 읽기 전용입니다. 키는 /api/v1 아래의 GET 경로만 열며 그 밖에는 아무것도 열지 않습니다. 여기 있는 어떤 경로도 무언가를 만들거나, 바꾸거나, 서명하거나, 쓰지 않습니다.

인증

모든 요청은 API 키를 베어러 토큰으로 담아 보냅니다.

Authorization: Bearer kurv_sk_...

키는 KURV 팀이 에이전트마다 하나씩 만들며, 만들 때 한 번만 보여집니다. KURV는 다이제스트만 보관하므로 잃어버린 키는 교체될 뿐 복구되지 않습니다. 키는 언제든 폐기할 수 있고, 폐기된 뒤의 다음 요청은 거절됩니다. 키가 없거나, 폐기된 키이거나, 경로의 스코프가 없는 키로 보낸 요청은 그 이유를 말하는 한 문장과 함께 401 또는 403을 받습니다.

스코프

스코프	여는 것
kurv:stats:read	/api/v1/stats/* 경로 4개: 수, 거래량, 수수료, 유입 경로. 어떤 응답에도 이메일이나 이름은 없습니다
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(또는 체인 ID 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 태그가 있는 주소에서 왔고 신청서 하나가 그 태그를 가지지만, 그런 주소는 누구나 입력할 수 있습니다. 2026년 10월 30일 이전의 태그는 둘 다 주지 않으며, 양식에 입력한 핸들도 마찬가지입니다.

모든 응답은 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회 요청할 수 있습니다. 이를 넘으면 retry-after 헤더와 함께 429가 돌아옵니다. 모든 응답은 길어야 60초 전의 것입니다. 서버는 1분에 한 번 읽고, read_at은 그 읽기의 시각입니다. 민팅을 일어나는 대로 따라가려면 마지막으로 본 read_at을 since에 넣어 /api/v1/stats/mints를 30초에서 60초마다 호출하세요. 열어 둘 스트림은 없습니다.

키가 할 수 없는 것

아무것도 못 합니다. 키는 읽기만 합니다. 컬렉션을 만들 수도, 런칭을 준비할 수도, 민팅하거나 거래할 수도, 프로필을 바꾸거나 초대를 건드릴 수도 없습니다. 컬렉션을 만들어야 하는 에이전트는 대신 본인의 승인을 받아 MCP로 연결하며, 그 연결은 어떤 키와도 별개입니다.

오류는 { "api_version": "1", "error": { "code": "...", "message": "..." } } 형태이며 상태 코드는 400, 401, 403, 429 또는 503입니다. 키가 필요 없는 공개 경로는 공개 API에, 모든 진입점은 KURV for Developers에 있습니다. 이 수치의 수수료는 각 컬렉션 자체의 것입니다. 수수료와 위험과 면책을 읽어 보세요.