빗썸 가상 자산 출금 API 가이드

📋 목차

1. API 기본 정보

엔드포인트, 인증 방식

2. 필수 파라미터

1 API 기본 정보

항목	값
엔드포인트	`POST /v1/withdraws/coin`
기본 URL	`https://api.bithumb.com`
인증 방식	JWT (HS256)
Content-Type	`application/json`

2 필수 파라미터

📝 예시 파라미터

{
  "currency": "USDT",           // 출금할 화폐 코드
  "net_type": "TRX",            // 출금 네트워크
  "amount": 3,                  // 출금 수량
  "address": "TW123aADADA7yKCVA73nLMYQcQKRwSaf7cK",  // 출금 주소
  "exchange_name": "upbit",     // 출금 거래소명
  "receiver_type": "personal",  // 수취인 타입 (personal/corporation)
  "receiver_ko_name": "임현성", // 수취인 한글명 ⭐
  "receiver_en_name": "IM HYEONSEONG"  // 수취인 영문명 ⭐
}

⚠️ 중요: receiver_ko_name은 한글 그대로 사용해야 합니다! receiver_ko_name과 receiver_en_name은 시 띄어쓰기 관계 없이 출금 가능합니다.

3 JWT 토큰 생성

🔐 JWT 페이로드 구성

payload = {
    'access_key': api_key,
    'nonce': str(uuid.uuid4()),
    'timestamp': round(time.time() * 1000),
    'query_hash': query_hash,        # 출금 API만 필요
    'query_hash_alg': 'SHA512'       # 출금 API만 필요
}

🔑 Query Hash 생성 (핵심!)

✅ 성공하는 방식

# Raw 문자열 방식
requestBody = dict(**params)

query_parts = []
for key, value in requestBody.items():
    query_parts.append(f"{key}={value}")
raw_query = "&".join(query_parts)
query = raw_query.encode('utf-8')

hash = hashlib.sha512()
hash.update(query)
query_hash = hash.hexdigest()

❌ 실패하는 방식

# URL 인코딩 방식 (공식 문서)
from urllib.parse import urlencode

query = urlencode(requestBody).encode()
# ❌ 한글이 %EC%9E%84... 로 변환됨
# ❌ 띄어쓰기가 + 로 변환됨

4 한글 처리 (성공의 핵심!) 🔥

🚨 핵심 발견: 빗썸 API는 공식 문서와 달리 한글과 띄어쓰기를 URL 인코딩하면 안 됩니다!

구분	공식 문서 방식	실제 작동 방식
방식	`urlencode()` 사용	Raw 문자열 직접 생성
한글 처리	`%EC%9E%84%ED%98%84%EC%84%B1`	`임현성` (원본 유지)
띄어쓰기	`IM+HYEONSEONG`	`IM HYEONSEONG` (원본 유지)
결과	❌ invalid_query_payload	✅ 201 Success

💡 핵심 포인트: receiver_ko_name=임현성&receiver_en_name=IM HYEONSEONG 형태로 Raw 문자열을 만들어야 성공합니다!

5 HTTP 요청 전송

📤 완전한 요청 예시

# 헤더 설정
headers = {
    'Authorization': f'Bearer {jwt_token}',
    'Content-Type': 'application/json'
}

# 요청 데이터 (JSON 형태)
json_data = json.dumps(requestBody)

# POST 요청 전송
response = await client.post(
    'https://api.bithumb.com/v1/withdraws/coin', 
    headers=headers, 
    data=json_data
)

✅ 성공 응답 예시 (201)

{
  "type": "withdraw",
  "uuid": "2511231977",
  "currency": "USDT",
  "net_type": "TRX", 
  "state": "processing",
  "created_at": "2025-08-07T03:24:31+09:00",
  "amount": "3.000000",
  "fee": "0.000000",
  "krw_amount": "4176"
}

6 문제 해결 가이드

에러	원인	해결책
`invalid_query_payload`	한글/띄어쓰기 URL 인코딩	Raw 문자열 방식 사용
`request_fail` 수취인 정보 누락	수취인 정보 미포함	`receiver_ko_name`, `receiver_en_name` 추가
`jwt_verification`	잘못된 JWT 토큰	API Key/Secret Key 확인
`NotAllowIP`	IP 미등록	빗썸에서 IP 화이트리스트 등록

🔧 디버깅 팁: 로그에서 Raw Query String과 JSON Data를 비교해보세요. 한글과 띄어쓰기가 동일하게 처리되어야 성공합니다!

🎯 핵심 요약

🔑

Raw 문자열 방식

urlencode() 대신 직접 문자열 조합

🇰🇷

한글 그대로

임현성 → 변환하지 않고 그대로

🎯

띄어쓰기 유지

IM HYEONSEONG → + 변환 안 함