이 API를 사용하려면 read.roulette 권한이 필요해요.
키는 한글이라 헤더에 넣기 전에 퍼센트 인코딩해야 해요. 인증 방법 →
룰렛 목록 조회
GET
/api/v1/roulette채널에 등록된 모든 룰렛 목록을 조회해요.
응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
roulettes | array | 룰렛 목록 |
roulettes[].uuid | string | 룰렛 고유 ID (UUID) |
roulettes[].name | string | 룰렛 이름 |
roulettes[].price | number | 룰렛 기본 가격 (치즈). 아래 조건을 만족할 때 이 금액을 후원하면 1회 돌아가요 |
roulettes[].items | array | 룰렛 항목 목록 |
roulettes[].items[].name | string | 항목 이름 |
roulettes[].items[].chance | number | 당첨 확률 (%) |
꺼진 룰렛도 함께 내려와요
이 목록은 삭제되지 않은 룰렛 전부를 돌려줘요. 꺼놓은 룰렛도 섞여 있어요.
그런데 응답에 활성 여부 필드가 없어서 켜짐/꺼짐을 구분할 방법이 없어요. 목록에 있다고 해서 그 룰렛이 돌아가는 상태라고 볼 수 없어요.
price 만큼 후원했을 때 실제로 돌려면 이것들이 모두 맞아야 해요.
- 방송 중일 것 — 방송이 꺼져 있으면 후원 룰렛 자체가 돌지 않아요.
- 룰렛이 켜져 있을 것 (확률 합계가 100이 아니면 자동으로 꺼집니다)
- 그 룰렛의 '룰렛 금액에 맞는 후원 감지시 즉발' 이 켜져 있을 것 (기본 켜짐)
- 키워드 감지 · 참여 권한 · 참여 제한 조건을 통과할 것
- 후원 종류가 채팅 후원일 것 — 기본값이 채팅 후원만이라 영상·미션 후원은 무시돼요.
매니저 이상이
!설정 룰렛 후원감지 모두를 입력해야 전부 인식해요.
요청
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/roulette" \
-H "Authorization: DDUBOT_API %EB%AF%B8%EB%A6%AC-%EC%9D%B8%EC%BD%94%EB%94%A9%ED%95%9C-%ED%82%A4"응답
{
"success": true,
"roulettes": [
{
"uuid": "550e8400-e29b-41d4-a716-446655440000",
"name": "일반 룰렛",
"price": 1000,
"items": [
{ "name": "1등 - 치킨", "chance": 5.0 },
{ "name": "2등 - 커피", "chance": 15.0 },
{ "name": "꽝", "chance": 80.0 }
]
},
{
"uuid": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
"name": "VIP 룰렛",
"price": 5000,
"items": [
{ "name": "대박", "chance": 10.0 },
{ "name": "중박", "chance": 30.0 },
{ "name": "소박", "chance": 60.0 }
]
}
]
}응답
{
"success": false,
"data": {
"error": "잘못된 접근입니다."
}
}룰렛 로그 조회
GET
/api/v1/roulette/logs특정 룰렛의 결과 기록을 페이지네이션으로 조회해요.
Query Parameters
uuidstring필수조회할 룰렛의 UUID
pagenumber기본값: 1페이지 번호
limitnumber기본값: 50페이지당 개수 (최대 50)
응답 필드
| 필드 | 타입 | 설명 |
|---|---|---|
data | array | 로그 목록 |
data[].user.name | string | 참여자 닉네임 (익명 시 "익명의 후원자") |
data[].user.uid | string | 참여자 UID (익명 시 "anonymous") |
data[].meta.isCompleted | boolean | 사용 처리 완료 여부 (대시보드 룰렛 기록의 '사용 여부') |
data[].meta.isTest | boolean | 테스트 여부 |
data[].meta.isAnonymous | boolean | 익명 참여 여부 |
data[].result | string | 룰렛 결과 |
pagination.page | number | 현재 페이지 |
pagination.total | number | 전체 로그 수 |
pagination.totalPages | number | 전체 페이지 수 |
요청
curl -X GET "https://chzzk-bot.ddutto.com/api/v1/roulette/logs?uuid=550e8400-e29b-41d4-a716-446655440000&page=1&limit=20" \
-H "Authorization: DDUBOT_API %EB%AF%B8%EB%A6%AC-%EC%9D%B8%EC%BD%94%EB%94%A9%ED%95%9C-%ED%82%A4"응답
{
"success": true,
"data": [
{
"user": {
"name": "열혈시청자",
"uid": "4c3a50fe635854036b4dcf15c9a4d0a2"
},
"meta": {
"isCompleted": true,
"isTest": false,
"isAnonymous": false
},
"result": "2등 - 커피"
},
{
"user": {
"name": "익명의 후원자",
"uid": "anonymous"
},
"meta": {
"isCompleted": false,
"isTest": false,
"isAnonymous": true
},
"result": "꽝"
}
],
"pagination": {
"page": 1,
"total": 150,
"totalPages": 8
}
}응답
{
"success": false,
"data": {
"error": "잘못된 룰렛 UUID 형식입니다."
}
}오류 코드
오류 메시지는 모두 data.error 안에 들어와요.
data.error | HTTP 상태 | 설명 |
|---|---|---|
| 잘못된 룰렛 UUID 형식입니다. | 400 | uuid 가 없거나 UUID 형식이 아님 |
| page는 1 이상의 정수여야 합니다. | 400 | 페이지 번호 오류 |
| limit는 1 이상의 정수여야 합니다. | 400 | limit 값 오류 |
| limit는 최대 50까지 가능합니다. | 400 | limit 값 초과 |
| page가 범위를 초과했습니다. | 400 | 존재하지 않는 페이지 |
| 잘못된 접근입니다. | 400 | API 키 인증 실패 |
| 권한이 없습니다. 'read.roulette' scope가 필요합니다. | 403 | 권한 없음 |
| 요청 횟수 제한을 초과했습니다. N초 후에 다시 시도해주세요. | 429 | 분당 호출 제한 초과 (계정 15회/분 · IP 60회/분) |
| 서버 오류가 발생했습니다. | 500 | 서버 내부 오류 |
limit 기본값은 50이에요
limit 을 생략하면 한 번에 50개를 가져와요. 최대값도 50이에요.
결과가 하나도 없으면 오류가 아니라 data: [] 와 pagination.total: 0, pagination.totalPages: 0 이 반환돼요.