Twitch Drops API 레퍼런스
진행 중인 모든 Twitch 드롭스와 보상 캠페인(1분마다 갱신), 그리고 Twitch 글로벌 채팅 배지를 제공하는 무료 JSON API입니다. 익명으로 호출하거나, 무료 API 키로 더 높은 한도를 이용하세요.
사용해 보기
경로
모든 경로는 GET 요청에 JSON으로 응답하며, 어떤 사이트의 브라우저에서도 API를 호출할 수 있습니다(CORS). /drops, /rewards, /badges 모두 가입이 필요 없으며, 무료 API 키가 있으면 각각의 한도가 올라갑니다.
세 경로 모두 같은 방식으로 응답합니다. 목록, 마지막으로 Twitch를 읽은 시각(refreshedAt), 내 요청 한도(rateLimit)입니다.
인증
/drops, /rewards, /badges를 읽는 데는 계정도 키도 필요하지 않습니다. 익명 호출은 IP 주소별로 집계되며, 한도는 각 경로에서 5분에 요청 1회입니다.
키는 무료입니다. Discord, Twitch 또는 GitHub로 로그인하고 대시보드에서 키를 만든 뒤 X-API-Key 헤더에 담아 보내세요. 키를 사용하면 한도가 기본 분당 요청 1회까지 높아지고(요청 시 추가 상향 가능), 트래픽도 확인할 수 있습니다.
키는 서버에 보관하세요. 키를 읽은 사람은 누구나 내 한도를 소모할 수 있습니다. 코드에 직접 쓰지 말고 환경 변수에서 읽어 오세요.
요청 헤더
# Anonymouscurl https://drops.sunkwi.com/api/twitch/drops
# With an API key, showing the rate-limit headerscurl -i -H "x-api-key: $DROPS_API_KEY" https://drops.sunkwi.com/api/twitch/drops무료 API 키 받기
키는 무료입니다. 각 경로의 한도가 5분에 요청 1회에서 분당 요청 1회까지 높아지고, 대시보드에서 트래픽을 확인할 수 있습니다.
- Discord, Twitch 또는 GitHub로 로그인합니다. 비밀번호도, 입력 양식도 없습니다.
- 대시보드에서 API 키를 열고 봇이나 사이트 이름으로 키를 만듭니다.
- 키가 표시되면(한 번만 표시됨) 복사하고, 서버에서
X-API-Key헤더에 담아 보냅니다.
드롭스 캠페인 가져오기
진행 중인 모든 드롭스 캠페인을 게임별로 묶어 마지막 Twitch 스캔 시각, 내 요청 한도와 함께 반환합니다. 게임당 games 항목 하나이며, 캠페인은 rewards에 들어 있습니다.
응답 본문
Game
DropCampaign, TimeBasedDrop, Benefit 필드
DropCampaign
TimeBasedDrop
Benefit
필드 이름은 Twitch에서 가져오며 바뀌지 않습니다. 새 필드가 추가될 수는 있지만 기존 필드는 유지됩니다.
응답 코드
curl https://drops.sunkwi.com/api/twitch/drops{ "games": [ { "gameId": "460630", "gameDisplayName": "Rainbow Six Siege", "gameBoxArtURL": "https://static-cdn.jtvnw.net/ttv-boxart/460630-120x160.jpg", "startAt": "2026-10-17T05:00:00Z", "endAt": "2026-11-02T13:59:59.999Z", "rewards": [ { "id": "ef80b803-…", "name": "R6S S2 2026 19", "startAt": "2026-10-17T05:00:00Z", "endAt": "2026-11-02T13:59:59.999Z", "firstSeenAt": "2026-10-17T05:00:41.208Z", "accountLinkURL": "https://drops-register.ubi.com", "timeBasedDrops": [ { "name": "Esports Pack", "requiredMinutesWatched": 120, "repeat": null, "benefitEdges": [{ "benefit": { "name": "Esports Pack", … } }] } ], … } ] }, … ], "refreshedAt": "2026-10-24T21:14:01.936Z", "rateLimit": { "limit": 1, "remaining": 0, "resetAt": "2026-10-24T21:15:12.000Z" }}보상 캠페인 가져오기
진행 중인 모든 보상 캠페인(Twitch 전체 이벤트, 채팅 배지, 파트너 보상)을 campaigns에 담아 마지막 Twitch 스캔 시각, 내 요청 한도와 함께 반환합니다.
응답 본문
RewardCampaign
보상 필드
RewardGroup
Reward
응답 코드
curl https://drops.sunkwi.com/api/twitch/rewards{ "campaigns": [ { "id": "19f00aac-…", "name": "First Partners Collection", "brand": "Pokemon", "status": "ACTIVE", "startsAt": "2026-08-24T17:00:00Z", "endsAt": "2026-11-01T07:00:00Z", "firstSeenAt": null, "isSitewide": true, "unlockRequirements": { "minuteWatchedGoal": 20, "subsGoal": 0 }, "rewards": [{ "name": "Great Ball", "earnableUntil": "2026-11-01T07:00:00Z", … }] }, { "id": "b7669f9e-…", "name": "GTAVI Launch Celebration", "brand": "Rockstar Games", "status": "UPCOMING", "startsAt": "2026-11-18T11:00:00Z", "endsAt": "2026-12-01T07:59:59.999Z", "unlockRequirements": { "minuteWatchedGoal": 60, "subsGoal": 0 }, "rewardGroups": [ { "id": "6a0e…", "unlockRequirements": { "minuteWatchedGoal": 60, "subsGoal": 0 }, "repeat": { "everyHours": 24, "times": 6 }, "categories": [{ "id": "1867279146", "displayName": "Grand Theft Auto VI", "slug": "grand-theft-auto-vi" }], "rewards": [{ "name": "GTA DVD Chest", … }] }, … ], … }, … ], "refreshedAt": "2026-10-24T21:14:01.936Z", "rateLimit": { "limit": 1, "remaining": 0, "resetAt": "2026-10-24T21:15:12.000Z" }}채팅 배지 가져오기
Twitch 글로벌 채팅 배지를 badges에 버전당 항목 하나씩 담고, 이 API가 알고 있으면 받는 방법(requirement)도 함께 제공합니다. 마지막으로 Twitch 배지를 읽은 시각과 내 요청 한도도 포함됩니다.
응답 본문
Badge
BadgeRequirement 필드
BadgeRequirement
드롭스 마이너용: requirement.watchTimeOnly 값이 true인 배지만 남기세요. 구독이 아니라 시청 시간만으로 배지를 주는 드롭스 캠페인에서 나온 배지입니다. startAt과 endAt도 확인하세요. 종료된 캠페인도 목록에 남습니다.
더 많은 것을 요구하는 배지도 있습니다. repeat이 있으면 기간마다 requiredMinutes를 다시 시청해 endAt 전까지 times회 채우세요. categories의 어느 채널 방송이든 인정됩니다. collection이 있으면 상자에서 원하는 것과 다른 배지가 나올 수 있고(chestSize), completeAll은 구독을 포함한 컬렉션 전체가 필요합니다. evolvesFrom이 있으면 시청 전에 그 배지를 장착하세요.
응답 코드
curl https://drops.sunkwi.com/api/twitch/badges요청 한도
경로마다 카운터가 따로 있습니다. /drops를 호출해도 /rewards나 /badges의 한도는 소모되지 않습니다. 캠페인은 1분에 한 번, 배지는 5분마다 바뀌므로 더 자주 폴링해도 새로운 내용은 없습니다.
응답 헤더
거부된 호출(429)도 호출로 집계됩니다. 다시 시도하기 전에 Retry-After만큼 기다리세요.
HTTP/1.1 429 Too Many Requestscontent-type: application/json; charset=utf-8retry-after: 214ratelimit-limit: 1ratelimit-remaining: 0ratelimit-reset: 214ratelimit-policy: 1;w=300
{ "code": "RATE_LIMITED" }오류
오류는 고정된 코드가 담긴 JSON 본문으로 응답합니다: { "code": "RATE_LIMITED" }. 코드는 절대 바뀌지 않으므로 메시지가 아닌 code를 기준으로 구현하세요.
HTTP/1.1 404 Not Foundcontent-type: application/json; charset=utf-8
{ "code": "NOT_FOUND" }사이트에서 API로
이 사이트의 모든 페이지는 이 경로들을 그대로 읽습니다. 각 페이지에 표시되는 내용이 응답의 어디에 있는지 정리했습니다.
게임 페이지 주소는 게임 이름으로 만들어집니다(Rocket League → /drops/rocket-league). 이는 이 사이트의 주소일 뿐 API 필드가 아니므로, 게임은 gameId로 대조하세요.