업비트 계정 안에 포켓을 하나 더 만들어 두면 무엇이 달라지는지 찾아보다가 문서마다 말이 다른 것처럼 느껴지신 적이 있으실 겁니다. 어떤 문서는 "포켓마다 독립적으로 동작한다"고 적어 두었고, 다른 문서는 "전체 포켓을 합산해 계산한다"고 적어 두었기 때문입니다. 두 문장은 서로 어긋나지 않습니다. 각각 다른 것을 가리키고 있을 뿐입니다.
먼저 누구에게 해당하는 이야기인지 못 박겠습니다. 포켓은 업비트 API를 쓰는 이용자에게만 열리는 기능입니다. 업비트 고객센터 「포켓 알아보기」는 개인회원과 법인회원을 함께 표시한 "이용 대상" 줄로 시작하고, 그 바로 다음 줄에 "포켓 기능은 업비트 API를 통해 이용하실 수 있습니다"라고 적었습니다. 같은 문서가 "포켓별 거래, 포켓 간 자산 이전 등은 업비트 API를 통해서만 진행할 수 있습니다"라고 다시 못 박았습니다. 앱이나 웹 화면에서 매매만 하시는 분께는 해당하지 않는 이야기입니다.
결론부터 적겠습니다. 첫째, 포켓마다 따로 굴러가는 것이 있습니다. 발급할 수 있는 권한의 구성, 포켓당 발급 가능한 API Key 개수, 거래·자산 관리 API의 요청 한도, 미체결 주문 일괄 취소의 대상 범위가 그렇습니다. 둘째, 포켓을 나눠도 계정 전체로 합쳐 세는 것이 있습니다. 24시간 디지털 자산 출금 지연제의 출금 한도, 코인빌리기 레벨 산정을 위한 거래대금, 에어드랍과 예치금 이용료의 지급 대상 수량이 그렇습니다. 셋째, 서브포켓에서는 아예 열리지 않는 자리가 있습니다. 외부 입출금, 입출금 관련 권한 네 개, 코인빌리기와 스테이킹이 그렇습니다.
아래 문장과 숫자는 2026년 8월 17일(KST)에 업비트 개발자센터와 고객센터에서 문서 원문을 직접 내려받아 옮긴 것입니다. 문서별 갱신 시각은 글 맨 아래 「확인한 자료」에 적어 두었습니다.
업비트 포켓 — 이 글이 다루지 않는 것
먼저 축을 그어 두겠습니다. 아래 세 가지는 이 글에서 다루지 않습니다.
| 다루지 않는 것 | 이유 |
|---|---|
| API Key를 안전하게 보관하는 방법 | 이 글은 키를 어떻게 지키느냐가 아니라, 포켓이라는 적용 단위가 무엇을 가르느냐만 봅니다 |
| 어떤 자산이 어떤 범주에 들어가는지에 관한 판정 | 이 글은 법령을 한 조도 열지 않습니다. 업비트가 스스로 낸 운영 문서만 읽습니다 |
| 수수료율이나 보상률 같은 값을 직접 재는 일 | 이 글에 나오는 숫자는 전부 문서가 이미 적어 둔 값이고, 제가 재서 얻은 값이 아닙니다 |
한 가지를 더 밝혀 두겠습니다. 이 글이 여는 문서는 열여섯 건이고 전부 업비트가 낸 것입니다. 개발자센터 열두 건과 고객센터 네 건이며, 목록은 맨 아래 「확인한 자료」에 전부 적어 두었습니다. 그러니 이 글이 말할 수 있는 범위도 그 열여섯 건이 적어 둔 자리까지입니다. 그 문서들이 적지 않은 것은 이 글도 적지 않았고, 적지 않았다는 사실 자체를 「이 글이 확인하지 못한 것」에 남겼습니다.
포켓을 만들기 전에 계정에서 끝나 있어야 하는 조건
서브포켓을 만들려면 계정 쪽에서 먼저 끝나 있어야 하는 것이 있습니다. 그런데 여기서 문서 두 곳이 요구하는 항목의 개수가 다릅니다. 개발자센터는 두 가지를 적었고, 고객센터는 세 가지를 적었습니다.
| 조건 | 적어 둔 문서 | 원문 |
|---|---|---|
| 고객 확인 · 2채널 인증 | 개발자센터 「API Key 발급 받기」 | "업비트 회원가입 후 고객 확인 및 2채널 인증(2FA)을 완료한 뒤에 API Key 발급이 가능합니다" |
| 고객확인 · 2채널 인증 · 입출금 계좌 인증 | 고객센터 「포켓 알아보기」 | "본 서비스는 고객확인, 2채널 인증 및 입출금 계좌 인증을 완료하신 회원님에 한해 이용 가능합니다" |
개발자센터 쪽 문장은 API Key 발급 조건을 말하고 있고, 고객센터 쪽 문장은 포켓 서비스 이용 조건을 말하고 있습니다. 두 문장이 가리키는 대상이 다르니 개수가 다른 것을 모순으로 읽으시면 안 됩니다. 다만 서브포켓을 쓰려는 분이라면 두 문장이 요구하는 항목을 모두 채워야 합니다.
고객센터 문서는 여기에 두 가지를 더 붙여 두었습니다. 첫째, 고객확인 재이행 대상인 회원은 고객확인을 완료한 이후에야 서브포켓 생성과 자산 이전을 할 수 있습니다. 둘째, "업비트 내 계정을 여러 개 보유하고 있는 경우 서브포켓 이용이 제한됩니다"라고 적고, "부계정 탈퇴 후 주계정에서 서브포켓을 생성할 수 있습니다"라고 덧붙였습니다. 계정이 하나뿐인 분께는 걸리지 않는 조건이지만, 예전에 만들어 두고 잊은 계정이 있다면 여기서 막힐 수 있습니다.
발급 화면 자체에도 조건이 있습니다. 개발자센터 「API Key 발급 받기」의 자주 들어오는 질문에 "Open API Key 발급 버튼이 활성화되지 않습니다" 항목이 있고, 그 아래에 조건이 불릿 세 줄로 적혀 있습니다. 기능 권한 중 하나 이상을 선택할 것, IP 주소 등록창에 하나 이상의 IP를 입력할 것, 개인정보 수집 및 이용 동의 체크박스를 클릭할 것. 같은 항목이 IP는 IPv4 형식만 지원한다는 점과, 한 IP 주소 안에 콤마가 들어갔는지 확인하라는 점을 함께 적어 두었습니다.
발급 환경에도 제약이 붙습니다. 같은 문서가 "업비트 API Key 발급은 PC 웹 환경에서만 가능합니다"라고 첫 불릿에 적었습니다. 반대로 출금 안심차단 해제는 모바일 앱 경로만 적혀 있습니다. 화면이 갈려 있으니 한쪽만 열어 두고 "안 된다"고 판단하시면 헛걸음을 하게 됩니다.
포켓마다 따로 굴러가는 것 — 권한 아홉 개와 요청 한도
개발자센터 「포켓(Pocket)」 문서에는 권한 표가 하나 있습니다. 표의 본문 행을 세어 보면 아홉 개입니다. 그 아홉 행을 그대로 옮기겠습니다.
| 권한명 | 주요기능 | 메인포켓 | 서브포켓 |
|---|---|---|---|
| 포켓관리 | 모든 포켓의 자산 조회, 자산 이전 실행 및 내역 조회, 포켓 정보 조회 | 지원 | 지원하지 않음 |
| 자산이전 | 해당 포켓 기준의 포켓 간 자산 이전 실행 및 이전 내역 조회 | 지원하지 않음 | 지원 |
| 자산조회 | 해당 포켓의 보유자산 및 잔고 조회 | 지원 | 지원 |
| 주문조회 | 해당 포켓의 체결 및 미체결 주문 내역 조회 | 지원 | 지원 |
| 주문하기 | 해당 포켓의 매수/매도 주문 접수 및 취소 | 지원 | 지원 |
| 출금조회 | 디지털 자산 및 원화 출금 내역 조회 | 지원 | 지원하지 않음 |
| 출금하기 | 디지털 자산 및 원화 출금 요청 | 지원 | 지원하지 않음 |
| 입금조회 | 디지털 자산 및 원화 입금 내역 조회 | 지원 | 지원하지 않음 |
| 입금하기 | 원화 입금 요청 및 트래블룰 검증 등 | 지원 | 지원하지 않음 |
메인포켓에서 고를 수 있는 권한은 여덟 개이고, 서브포켓에서 고를 수 있는 권한은 네 개입니다. 표의 각 행에서 체크 표시가 켜져 있는지를 하나씩 세어 얻은 값입니다. 메인포켓은 아홉 개 중 자산이전 하나만 빠져 여덟 개이고, 서브포켓은 자산이전과 자산조회, 주문조회, 주문하기 네 개입니다.
여기서 한 행이 방향이 반대입니다. 자산이전은 아홉 행 중 유일하게 메인포켓에 표시가 없고 서브포켓에만 표시가 있는 행입니다. 메인포켓 쪽에서 자산을 옮기는 일은 자산이전이 아니라 포켓관리 권한이 맡고, 서브포켓 쪽에서 옮기는 일만 자산이전이 맡기 때문입니다. 이 갈림은 뒤에서 자산 이전 API 두 건을 나란히 놓고 다시 보겠습니다.
서브포켓 쪽에 표시가 없는 네 개는 출금조회, 출금하기, 입금조회, 입금하기입니다. 고객센터 「포켓 알아보기」도 같은 취지를 한 문장으로 적었습니다. "출금조회, 출금하기, 입금조회, 입금하기 권한 선택은 메인포켓에서만 가능합니다." 개발자 문서의 표와 고객센터의 문장이 같은 네 개를 가리키고 있습니다.
포켓 축에서 따로 굴러가는 값이 또 있습니다. 개수 제한입니다. 그런데 여기에 함정이 하나 있어 표로 갈라 두겠습니다.
| 무엇의 개수인가 | 상한 | 적어 둔 문서 |
|---|---|---|
| 계정 안에 만들 수 있는 서브포켓 | 최대 5개 | 고객센터 「포켓 알아보기」 |
| 메인포켓에서 발급 가능한 API Key | 최대 10개 | 개발자센터 「API Key 발급 받기」 |
| 서브포켓 하나당 발급 가능한 API Key | 최대 5개 | 개발자센터 「API Key 발급 받기」 |
| API Key 하나에 등록 가능한 허용 IP | 최대 10개 | 개발자센터 「인증」 |
첫째 줄의 5와 셋째 줄의 5는 서로 다른 5입니다. 앞의 5는 포켓의 개수이고 뒤의 5는 포켓 하나가 가질 수 있는 키의 개수입니다. 두 값을 한 문장에 붙여 읽으면 "서브포켓은 5개까지, 키도 5개까지"라는 인상이 남는데 실제로는 서브포켓 다섯 개를 다 만들면 서브포켓 쪽 키만 최대 스물다섯 개가 됩니다. 마찬가지로 둘째 줄의 10과 넷째 줄의 10도 다른 값입니다. 앞은 포켓 하나가 가질 수 있는 키의 개수이고, 뒤는 키 하나가 가질 수 있는 IP의 개수입니다.
마지막으로 요청 한도입니다. 「포켓(Pocket)」 문서 아래쪽 안내 상자에 이렇게 적혀 있습니다. "거래 및 자산 관리(Exchange) API의 Rate Limit은 포켓(Pocket) 단위로 적용됩니다. 동일 포켓에서 발급된 API Key는 요청 한도를 공유하며, 서로 다른 포켓은 각각 독립적인 요청 한도를 가집니다." 키를 더 뽑아도 같은 포켓 안이면 한도는 하나입니다. 이 대목은 다음 절에서 자세히 보겠습니다.
2026년 6월 25일에 바뀐 것과 바뀌지 않은 것
요청 한도의 측정 단위는 원래 계정이었습니다. 개발자센터 공지 「[안내] 거래소 API Rate Limit 적용 단위 변경 (계정 → 포켓)」이 "적용 일시"로 "2026-06-25 (목)"을 적었습니다. 바뀐 것은 한도를 차감하는 기준이지 한도의 크기가 아닙니다. 공지의 변경 내용 표가 "그룹별 한도"에 대해 변경 전과 변경 후를 모두 "변경 없음"으로 적어 두었고, 그 아래 인용문이 "그룹별 초당 최대 요청 수(예: exchange.default 그룹은 초당 30회)는 그대로입니다. 한도를 차감하는 기준만 계정에서 포켓으로 바뀝니다"라고 다시 밝혔습니다.
바뀐 대상도 전부가 아닙니다. 공지의 영향 범위 표는 다섯 줄인데, 그중 변경 표시가 붙은 것은 두 줄입니다.
| 기능 분류 | 변경 전 | 변경 후 |
|---|---|---|
| 거래·자산 관리(Exchange) REST API | 계정 | 포켓 |
| 인증 포함 WebSocket 연결 | 계정 | 포켓 |
| 시세 조회(Quotation) REST API | IP | IP |
| 인증 미포함 WebSocket 연결 | IP | IP |
| WebSocket 데이터 요청 | 커넥션 | 커넥션 |
같은 공지가 표 아래에 "변경 대상 그룹은 exchange.default / exchange.order / exchange.order-test / exchange.order-cancel-all입니다"라고 적었습니다. 슬래시로 나뉜 그룹 이름은 네 개입니다. 이 네 그룹의 한도값은 개발자센터 「요청 수 제한(Rate Limits)」의 그룹 표에서 확인할 수 있습니다.
| Rate Limit 그룹 | 정책 | 적용 단위 |
|---|---|---|
| exchange.default | 초당 최대 30회 | 포켓 |
| exchange.order | 초당 최대 8회 | 포켓 |
| exchange.order-test | 초당 최대 8회 | 포켓 |
| exchange.order-cancel-all | 2초당 최대 1회 | 포켓 |
주문 생성과 취소 후 재주문이 들어가는 exchange.order는 초당 8회이고, 주문 일괄 취소가 들어가는 exchange.order-cancel-all은 초당이 아니라 2초당 1회입니다. 단위 자체가 다르니 이 줄만은 눈으로 한 번 더 확인하시는 편이 좋습니다.
「요청 수 제한(Rate Limits)」에는 측정 단위를 따로 정리한 표도 있습니다. 그 표는 네 줄입니다. 시세 조회 REST API는 IP, 거래·자산 관리 REST API는 포켓, WebSocket 연결 요청은 IP 또는 포켓, WebSocket 데이터 요청은 커넥션입니다. 셋째 줄이 둘로 갈리는 이유는 같은 문서가 적어 두었습니다. "인증 없이 연결하면 IP, 인증 정보를 포함해 연결하면 포켓 단위로 측정됩니다."
같은 문서가 계정 전체 처리량을 계산해 보인 대목도 있습니다. "메인포켓 1개와 서브포켓 5개가 각각 exchange.default(초당 30회)를 사용하면, 계정 전체로는 초당 최대 180회까지 처리할 수 있습니다. 개별 포켓의 한도는 30회로 동일합니다." 개별 포켓의 한도는 그대로이고 포켓 수만큼 곱해진다는 뜻입니다. 같은 문서가 뒤에서 결론을 한 줄로 적었습니다. "처리량을 늘리려면 API Key가 아니라 포켓을 분리해 발급해야 합니다." 공지 쪽 유의사항도 같은 말을 다르게 적었습니다. "같은 포켓의 여러 API Key는 하나의 한도를 공유합니다. 처리량을 늘리시려면 API Key를 추가 발급하는 대신 서브포켓을 분리해 운영해 주시기 바랍니다."
차단도 포켓 단위입니다. 공지가 "일시 차단(HTTP 418)도 포켓 단위로만 적용됩니다"라고 적었고, 「요청 수 제한(Rate Limits)」의 오류 표는 418을 "429 누적으로 일시 차단 (동일 IP·포켓·커넥션 단위)"으로 적었습니다. 자체 카운터로 잔여 요청 수를 세고 계신 경우에 대해서는 공지가 따로 한 줄을 붙였습니다. "기준을 계정이 아니라 포켓 단위로 분리해 주시기 바랍니다." 반대로 응답 헤더 Remaining-Req의 sec 값으로 관리하는 경우에는 "별도의 코드 변경 없이 정상 동작합니다"라고 적혀 있습니다.
계정 전체로 합쳐 세는 것 — 출금 지연제 한도와 지급 대상 수량
여기서 방향이 반대로 바뀝니다. 고객센터 「포켓 알아보기」의 유의사항 문단이 합산이라고 밝힌 항목이 있습니다. 그 문단 안에서만 세면 네 가지입니다.
| 합쳐 세는 것 | 원문 |
|---|---|
| 24시간 디지털 자산 출금 지연제의 출금 한도 | "24시간 디지털 자산 출금 지연제의 출금 한도와 코인빌리기 레벨 산정을 위한 거래대금은 전체 포켓을 합산해 계산합니다" |
| 코인빌리기 레벨 산정을 위한 거래대금 | 위와 같은 문장 |
| 에어드랍의 지급 대상 수량 | "에어드랍 및 예치금이용료는 계정 내 모든 포켓의 잔고를 합산하여 지급 대상 수량을 산정하며, 지급은 메인포켓으로 이루어집니다" |
| 예치금이용료의 지급 대상 수량 | 위와 같은 문장 |
여기서 한 가지를 정확히 적겠습니다. 이 네 가지는 "그 문단이 합산이라고 밝힌 항목"이지 "합산되는 것 전부"가 아닙니다. 다른 문서에 또 있는지는 이번에 확인하지 못했고, 그 사실은 아래 「이 글이 확인하지 못한 것」에 남겼습니다.
이 문장에는 방향이 하나 더 들어 있습니다. 산정은 합산이고 지급은 메인포켓입니다. 서브포켓 잔고도 지급 대상 수량 계산에는 들어가지만, 실제로 들어오는 자리는 메인포켓 한 곳이라는 뜻입니다. 그러니 서브포켓 쪽 잔고만 조회하고 "안 들어왔다"고 판단하시면 어긋납니다. 예치금 이용료가 얼마이고 언제 지급되는지는 이 문서가 정하지 않으며, 요율과 지급 시점은 예치금 이용료를 따로 다룬 글에 정리해 두었습니다.
계정 축에서 걸리는 설정이 또 하나 있습니다. 고객센터 「보안이 걱정돼요. 출금·주문 잠금은 어떻게 설정하나요?」가 매수·매도 주문 잠금의 유의사항에 이렇게 적었습니다. "업비트 API의 메인포켓 및 서브포켓을 통해 접수한 주문도 제한됩니다." 포켓을 나눠 두어도 이 잠금은 포켓을 가리지 않습니다. 같은 문서가 설정 경로를 모바일 앱 하나로만 적었고("스스로 잠금 기능은 모바일 앱에서만 설정 가능합니다"), 해제에 대해서는 "잠금 해제는 고객센터를 통한 본인확인 절차가 필요합니다"와 "해제까지 1영업일이 소요될 수 있습니다"를 적었습니다. 켜는 것은 앱에서 바로 되고 끄는 것은 그렇지 않다는 비대칭입니다.
서브포켓에서는 열리지 않는 자리와, 메인포켓을 거쳐야 하는 경로
서브포켓에서 아예 열리지 않는 자리를 문서 문장 그대로 모으겠습니다.
| 열리지 않는 것 | 원문 | 문서 |
|---|---|---|
| 원화·디지털 자산의 외부 입출금 | "원화 및 디지털 자산의 입출금은 메인포켓에서만 가능합니다" | 「포켓 알아보기」 |
| 외부 주소로 직접 출금 | "서브포켓에 보유 중인 디지털 자산은 외부 주소로 직접 출금할 수 없으며, 메인포켓으로만 출금할 수 있습니다" | 「Open API를 통해 출금하고 싶어요.」 |
| 코인빌리기·스테이킹 등 | "서브포켓에서는 거래만 가능하며 코인빌리기, 스테이킹 등 다른 서비스는 이용할 수 없습니다" | 「포켓 알아보기」 |
| 입출금 관련 권한 네 개 | "출금조회, 출금하기, 입금조회, 입금하기 권한 선택은 메인포켓에서만 가능합니다" | 「포켓 알아보기」 |
세 번째 줄과 네 번째 줄은 성격이 다릅니다. 네 번째 줄은 권한 선택 화면에서 항목 자체가 열리지 않는다는 뜻이고, 세 번째 줄은 권한과 무관하게 서비스가 열리지 않는다는 뜻입니다. 스테이킹 쪽 조건이 궁금하시면 스테이킹 보상 지급 주기를 다룬 글을 참고하시되, 그 글의 조건은 메인포켓 기준으로 읽으셔야 합니다.
경로도 하나 정해져 있습니다. 「포켓 알아보기」가 "서브포켓의 자산을 출금하시려면 먼저 업비트 API를 통해 메인포켓으로 자산을 이전해야 합니다"라고 적었습니다. 「Open API를 통해 출금하고 싶어요.」도 같은 취지로 "Open API를 통한 디지털 자산 일반 출금은 메인포켓에 보유 중인 디지털 자산에 한해, 등록된 출금 주소로만 가능합니다"라고 적었습니다. 서브포켓에서 밖으로 나가는 직선 경로는 없고, 메인포켓을 한 번 거치는 경로만 있습니다.
보이는 화면에도 제약이 있습니다. 「포켓 알아보기」가 "서브포켓 자산은 업비트 API의 '자산조회 API'에서만 확인할 수 있습니다"라고 적고, "업비트 API 외 업비트 앱/웹에서는 서브포켓 자산이 표시되지 않으니, 포켓별 자산 확인 시에는 업비트 API를 이용해 주세요"라고 덧붙였습니다.
자전거래에 관한 안내도 한 줄 있습니다. "업비트는 본인 주문 간 체결을 차단하는 자전체결 방지(SMP) 기능을 지원합니다. 포켓 간 자전거래가 발생하지 않도록 API 주문 파라미터에 SMP를 설정해 주세요." 포켓을 나눠 두어도 같은 사람의 주문이라는 사실은 달라지지 않으니, 설정은 이용자 쪽에서 걸어야 한다는 안내입니다.
한 줄만 덧붙이겠습니다. 출금하기 권한 자체가 서브포켓에서 열리지 않으므로, 2026년 7월 9일 15:00 이후 출금하기 권한을 포함해 새로 발급한 API Key에 자동 적용된다는 출금 안심차단도 서브포켓 키에는 걸릴 자리가 없습니다. 그 차단은 「Open API를 통해 출금하고 싶어요.」가 "출금 안심차단은 API Key별로 적용됩니다"라고 적은 대로 키 축의 이야기이고, 이 글의 포켓 축과는 결이 다릅니다.
자산 이전 두 API — 주소부터 갈립니다
앞에서 미뤄 둔 자산이전 권한의 방향을 여기서 마저 보겠습니다. 개발자센터에는 자산 이전 문서가 두 건 있고, 두 문서가 정의한 주소가 서로 다릅니다. 「메인포켓 자산 이전」의 OpenAPI 정의는 POST /v1/pockets/universal_transfers이고, 「서브포켓 자산 이전」의 정의는 POST /v1/pockets/transfers입니다. 두 문서에 실린 curl·파이썬·Node·자바 예제도 각각 그 주소를 그대로 씁니다.
여기서 걸려 넘어지기 쉬운 자리를 미리 밝혀 두겠습니다. 「포켓 정보 조회」 문서의 흐름도는 두 갈래를 모두 POST /v1/pockets/transfers로 줄여 그려 두었습니다. 그림만 보면 두 API가 한 주소를 나눠 쓰는 것처럼 읽히는데, 실제로 호출되는 주소를 정하는 것은 각 문서의 OpenAPI 정의와 코드 예제 쪽입니다. 그림과 정의가 어긋나면 정의를 따르셔야 합니다.
| 문서 | 엔드포인트 | 쓸 수 있는 포켓 | 필요한 권한 | 기본값 규칙 |
|---|---|---|---|---|
| 메인포켓 자산 이전 | POST /v1/pockets/universal_transfers | 메인포켓만 | 포켓관리 | from을 지정하지 않으면 요청에 쓴 API Key가 속한 포켓 UUID가 기본값 |
| 서브포켓 자산 이전 | POST /v1/pockets/transfers | 서브포켓에서만 | 자산이전 | to를 지정하지 않으면 기본적으로 메인포켓으로 이전 |
기본값이 서로 다른 자리에 붙어 있다는 점이 중요합니다. 메인포켓 쪽 문서는 보내는 쪽(from)의 기본값을 정해 두었고, 서브포켓 쪽 문서는 받는 쪽(to)의 기본값을 정해 두었습니다. 서브포켓 키로 to를 비워 두고 부르면 메인포켓으로 모이게 되어 있다는 뜻입니다.
두 문서가 함께 적어 둔 유의사항도 있습니다. 같은 포켓끼리는 이전할 수 없다는 것(from과 to가 같으면 안 됩니다), 요청마다 고유한 identifier를 쓸 수 있고 그 값은 이전 성공 여부와 관계없이 한 번만 쓸 수 있다는 것, identifier의 허용 규격이 1~64자 안의 문자·숫자·언더스코어·점·하이픈이라는 것입니다. 이전 요청의 상태는 네 가지로 적혀 있습니다. submitted(요청 접수), processing(처리 중), done(처리 완료), failed(처리 실패)입니다.
조회 쪽 권한도 나란히 놓고 보면 갈림이 보입니다.
| API | 쓸 수 있는 포켓 | 필요한 권한 |
|---|---|---|
| 포켓 정보 조회 (GET /v1/pockets) | 메인포켓만 | 포켓관리 |
| 포켓별 API Key 목록 조회 | 메인포켓만 | 포켓관리 |
서브포켓 잔고 조회 (GET /v1/pockets/assets) | 메인포켓만 | 포켓관리 |
| 포켓 잔고 조회 | 제한 표기 없음 | 자산조회 |
| 주문 일괄 취소 | 제한 표기 없음 | 주문하기 |
이 표의 셋째 줄에는 주소가 갈리는 자리가 하나 더 있어 밝혀 두겠습니다. 「서브포켓 잔고 조회」 문서의 흐름도는 GET /v1/pockets/asset으로 적어 두었지만, 같은 문서의 OpenAPI 정의와 curl·파이썬·Node·자바 예제는 모두 GET /v1/pockets/assets입니다. 앞 절의 자산 이전과 같은 유형의 어긋남이라 위 표에는 정의 쪽 주소를 적었습니다.
서브포켓 잔고를 조회하는 API가 메인포켓 전용이라는 점도 눈에 걸립니다. 이름은 서브포켓이지만 부르는 쪽은 메인포켓 키입니다. 서브포켓 자신의 잔고는 포켓 잔고 조회로 볼 수 있고 그쪽은 자산조회 권한이면 됩니다. 즉 다른 포켓을 들여다보는 일이 포켓관리 권한에 묶여 있고, 자기 포켓을 보는 일은 자산조회 권한에 묶여 있습니다. 「포켓 정보 조회」 문서가 조회한 포켓 UUID를 "포켓별 API Key 목록 조회, 서브포켓 잔고 조회, 메인포켓·서브포켓 간 자산 이전 및 자산 이전 내역 조회 등의 기능을 수행하기 위한 식별자"라고 설명한 것도 같은 구조를 보여 줍니다.
미체결 주문 일괄 취소는 세 문서가 같은 값을 적었습니다. 「포켓 알아보기」가 "선택한 포켓의 미체결 주문을 최대 300건까지 일괄로 취소할 수 있습니다. (메인포켓/서브포켓 모두 가능)"이라고 적었고, 「업비트 API란 무엇인가요? 어떻게 시작하나요?」도 "한 번에 300건까지"라고 적었으며, 개발자센터 「주문 일괄 취소」 문서는 "조건을 지정하여 해당 조건을 만족하는 최대 300개의 주문을 일괄 취소합니다"라고 적었습니다. 그 개발자 문서에는 고객센터에 없는 값이 하나 더 있습니다. 취소할 주문의 최대 개수를 지정하지 않으면 기본값이 20입니다. 300은 지정할 수 있는 최댓값이지 기본값이 아닙니다.
이전 뒤에 화면 숫자가 달라지는 경우도 안내돼 있습니다. 「포켓 알아보기」가 "포켓 간 자산 이전 시, 포켓 간 자산 이전 시점의 마지막 체결가가 매수평균가에 반영되어 포켓별 매수평균가가 기존과 다르게 표시될 수 있습니다"라고 적었습니다. 표시가 달라지는 것 자체는 안내된 동작입니다. 거래 기록을 서류로 남겨야 할 일이 있으시면 거래내역서 발급이 막히는 지점을 다룬 글을 함께 보시기 바랍니다.
만들고 나면 되돌릴 수 없는 설정과 1년이라는 시한
포켓 쪽에서 되돌릴 수 없는 것이 하나 있습니다. 「포켓 알아보기」가 이용 방법 절에 별표를 붙여 적었습니다. "서브포켓 생성 후에는 포켓을 삭제하거나 포켓명을 수정할 수 없으니 이용에 참고 부탁드립니다." 이름을 나중에 고칠 수 없으니, 서브포켓을 만들기 전에 이름부터 정하시는 편이 낫습니다. 개수도 다섯 개가 상한이니 시험 삼아 하나 만들어 보는 선택의 값이 생각보다 큽니다.
시한이 붙는 것도 있습니다. API Key는 발급일로부터 1년간 유효하고 연장할 수 없습니다. 이 문장의 출처를 정확히 밝혀 두겠습니다. 제가 이 문장을 읽은 곳은 고객센터 「업비트 API란 무엇인가요? 어떻게 시작하나요?」의 마지막 줄입니다. 원문은 "※ API Key는 발급일로부터 1년간 유효하며, 연장할 수 없습니다."입니다. 개발자센터 「API Key 발급 받기」 쪽에는 이 기간 숫자가 없습니다. 그 문서에는 만료된 키를 지우는 절차와 만료 관련 오류 코드만 있습니다. 그러니 유효기간을 인용하실 때는 개발자 문서가 아니라 고객센터 문서를 근거로 드셔야 합니다.
만료가 실제로 화면에서 어떻게 드러나는지도 개발자센터 자주 들어오는 질문에 적혀 있습니다.
| 증상 | 문서가 적어 둔 처리 |
|---|---|
expired_access_key 오류 | "API 키가 만료되었습니다. Open API 관리 페이지에서 만료된 키를 삭제하고, 신규키를 발급받길 바랍니다" |
no_authorization_ip 오류 | "등록되지 않은 클라이언트 IP에서 요청이 발생했습니다. 요청 환경을 확인한 후 허용 IP 주소를 변경(추가)하고 다시 요청해 주세요" |
open_api_withdraw_locked 오류 | 해당 키에 출금 안심차단이 설정돼 있어 출금이 불가하며, 모바일 앱 경로에서 해지 |
| 등록된 키가 없는데 "최대 Open API 토큰 발급 수량을 초과했습니다" 안내 | "만료된 Key 탭으로 이동하여 조회되는 만료된 Key를 삭제하시고 다시 등록해보시길 바랍니다" |
마지막 줄이 앞에서 본 개수 상한과 이어집니다. 만료된 키도 발급 수량에는 남아 있다는 뜻으로 읽힙니다. 메인포켓 열 개, 서브포켓당 다섯 개라는 상한을 채운 것 같지 않은데 발급이 막힌다면, 만료된 키 탭을 먼저 열어 보라는 것이 문서가 적어 둔 순서입니다. 문서는 그 이상을 설명하지 않으므로, 실제로 상한을 어떻게 세는지에 대해서는 이 글도 여기까지만 적겠습니다.
이 글이 확인하지 못한 것
- 다른 거래소의 대응 기능은 열지 못했습니다. 코인원 쪽 문서를 찾으려고 두 주소를 열어 보았고 둘 다 HTTP 404를 받았습니다.
https://docs.coinone.co.kr/reference/portfolio와https://support.coinone.co.kr/hc/ko입니다. 다른 블로그나 요약글의 서술을 근거로 대신 쓰지 않았습니다. 그래서 이 글은 업비트 한 곳의 문서만 다룹니다. - 합산되는 항목이 네 가지뿐인지는 확인하지 못했습니다. 위에 적은 네 가지는 「포켓 알아보기」의 유의사항 문단 안에서만 센 값입니다. 다른 고객센터 문서나 개별 이벤트 공지에 또 있을 수 있고, 그 범위까지는 이번에 열지 않았습니다.
- 화면 스크린샷은 직접 보지 못했습니다. 포켓 생성과 API Key 발급은 로그인과 인증을 거쳐야 열리는 화면입니다. 이 글의 화면 관련 서술은 전부 업비트가 문서에 적어 둔 경로 표기를 옮긴 것이고, 제가 그 화면을 열어 확인한 것이 아닙니다.
- 한도값은 바뀔 수 있다고 문서가 스스로 적었습니다. 「요청 수 제한(Rate Limits)」이 "Rate Limit 그룹별 초당 최대 허용 요청 수는 서비스 정책에 따라 공지 후 변경되거나, 서비스 상황에 따라 추가 제한이 발생할 수 있습니다"라고 적었습니다. 위 표의 숫자는 제가 받은 판본의 값입니다.
- 서브포켓 다섯 개라는 상한이 회원 유형에 따라 갈리는지는 확인하지 못했습니다. 「포켓 알아보기」는 이용 대상에 개인회원과 법인회원을 모두 표시해 두었지만, 개수 상한을 유형별로 나눠 적지는 않았습니다. 유형별로 다른 값이 적용되는지 여부는 제가 연 네 건의 고객센터 문서에서는 조회되지 않았습니다.
- 포켓별 잔고를 서류로 받는 방법은 다루지 않았습니다. 증명서 발급 쪽은 이 글이 연 열여섯 건의 문서 범위 밖입니다.
- 문서는 조회 시점의 것입니다. 거래소가 공지 없이 화면 경로와 숫자를 바꾸는 일이 있으므로, 인용하실 때는 아래 「확인한 자료」의 갱신 시각을 함께 확인하시고 필요하면 원문을 다시 여시기 바랍니다.
자주 묻는 질문
Q: 서브포켓을 만들면 요청 한도가 늘어나나요? A: 거래·자산 관리(Exchange) API를 쓰시는 경우라면 늘어납니다. 2026년 6월 25일부터 그 API의 한도가 포켓 단위로 차감되기 때문에, 포켓을 하나 더 운영하면 그 포켓이 독립된 한도를 하나 더 갖습니다. 다만 시세 조회 REST API와 인증 없이 맺는 WebSocket 연결은 여전히 IP 단위이고, WebSocket 데이터 요청은 커넥션 단위이므로 이쪽은 포켓을 늘려도 달라지지 않습니다. 개별 포켓의 한도값 자체도 그대로입니다.
Q: 같은 포켓 안에서 API Key를 여러 개 발급하면 한도가 늘어나나요? A: 늘어나지 않습니다. 개발자센터 문서가 "동일 포켓에서 발급된 API Key는 요청 한도를 공유하며"라고 적었고, 공지도 "처리량을 늘리시려면 API Key를 추가 발급하는 대신 서브포켓을 분리해 운영해 주시기 바랍니다"라고 적었습니다. 키를 나누는 것은 권한과 IP를 나누는 데 쓰는 수단이지 한도를 늘리는 수단이 아닙니다.
Q: 서브포켓에 있는 코인을 외부 지갑으로 바로 보낼 수 있나요? A: 보낼 수 없습니다. 고객센터 문서가 "서브포켓에 보유 중인 디지털 자산은 외부 주소로 직접 출금할 수 없으며, 메인포켓으로만 출금할 수 있습니다"라고 적었습니다. 밖으로 보내시려면 먼저 업비트 API로 메인포켓에 자산을 이전한 뒤, 메인포켓에서 등록된 출금 주소로 보내야 합니다. 출금하기 권한 자체도 메인포켓에서만 선택할 수 있습니다.
Q: 서브포켓에 넣어 둔 자산도 에어드랍 대상에 들어가나요? A: 「포켓 알아보기」의 유의사항 문단만 놓고 보면, 지급 대상 수량은 "계정 내 모든 포켓의 잔고를 합산하여" 산정한다고 적혀 있습니다. 다만 같은 문장이 "지급은 메인포켓으로 이루어집니다"라고 이어지므로, 산정 자리와 지급 자리가 다르다는 점을 함께 보셔야 합니다. 개별 에어드랍마다 별도 조건을 공지하는 경우가 있는데 그 공지들까지는 이번에 열지 않았습니다.
Q: 서브포켓 이름을 잘못 지었는데 고칠 수 있나요? A: 고객센터 문서 기준으로는 고칠 수 없습니다. "서브포켓 생성 후에는 포켓을 삭제하거나 포켓명을 수정할 수 없으니 이용에 참고 부탁드립니다"라고 적혀 있습니다. 삭제도 같은 문장에 함께 묶여 있고, 생성 개수는 최대 다섯 개가 상한입니다. 그러니 만들기 전에 이름을 정해 두시는 편이 안전합니다.
Q: API Key 발급 버튼이 눌리지 않는데 무엇을 확인해야 하나요? A: 개발자센터 자주 들어오는 질문이 조건 세 가지를 적어 두었습니다. 기능 권한 중 하나 이상을 선택했는지, IP 주소 등록창에 하나 이상의 IP를 입력했는지, 개인정보 수집 및 이용 동의 체크박스를 클릭했는지입니다. 세 가지를 다 채웠는데도 눌리지 않는다면 발급 환경을 확인하십시오. 같은 문서가 발급은 PC 웹 환경에서만 가능하다고 적었습니다. 그래도 안 되고 "최대 Open API 토큰 발급 수량을 초과했습니다"라는 안내가 뜬다면, 만료된 Key 탭에서 조회되는 키를 삭제해 보라는 것이 문서가 적어 둔 순서입니다.
Q: 앱에서 스스로 잠금을 걸어 두면 서브포켓 주문도 막히나요? A: 매수·매도 주문 잠금을 거신 경우라면 막힙니다. 고객센터 문서가 유의사항에 "업비트 API의 메인포켓 및 서브포켓을 통해 접수한 주문도 제한됩니다"라고 적었습니다. 이미 걸어 둔 것에 대해서는 같은 문서가 두 줄로 나누어 적었으므로 두 줄을 함께 보셔야 합니다. 앞 줄은 "기존에 신청된 주문(예약주문 포함) 및 코인모으기는 취소되지 않습니다"이고, 바로 다음 줄은 "단, 코인모으기는 주문잠금 기간 중에는 실패 처리되며, 자동 주문 실행이 연속 10회 실패 시 해당 모으기 건은 해지되오니 이 점은 유의부탁드립니다"입니다. 앞 줄만 떼어 읽으면 어긋납니다. 기존 주문과 예약주문은 잠금 때문에 취소되지 않지만, 코인모으기는 잠금 기간 중 자동 주문이 실패로 처리되고 그 실패가 연속 열 번 쌓이면 해당 모으기 건이 해지됩니다. 해제는 고객센터를 통한 본인확인 절차가 필요하고 1영업일이 걸릴 수 있다고 적혀 있으니, 잠깐 막아 두는 용도로 생각하시면 어긋납니다.
Q: 서브포켓 잔고가 앱에 안 보이는데 문제가 생긴 건가요? A: 문서가 적어 둔 정상 동작입니다. "업비트 API 외 업비트 앱/웹에서는 서브포켓 자산이 표시되지 않으니, 포켓별 자산 확인 시에는 업비트 API를 이용해 주세요"라고 적혀 있습니다. 확인하시려면 자산조회 권한이 붙은 키로 그 포켓의 잔고를 조회하시거나, 메인포켓의 포켓관리 권한이 붙은 키로 서브포켓 잔고 조회를 부르셔야 합니다. 두 방법이 요구하는 권한이 다르다는 점만 유의하시기 바랍니다.
정리
- 포켓은 자산을 나누는 칸이 아니라 규칙의 적용 단위를 나누는 칸입니다. 어떤 규칙은 포켓마다 따로 굴러가고, 어떤 규칙은 포켓을 나눠도 계정 전체로 합쳐 셉니다.
- 권한 표의 본문 행은 아홉 개입니다. 메인포켓에서 고를 수 있는 것은 여덟 개, 서브포켓에서 고를 수 있는 것은 네 개입니다. 자산이전만 방향이 반대여서 서브포켓에만 표시가 있습니다.
- 다섯이라는 값이 두 자리에 있습니다. 서브포켓은 계정당 최대 다섯 개이고, 서브포켓 하나당 API Key는 최대 다섯 개입니다. 메인포켓 쪽 키는 최대 열 개이고, 키 하나에 등록할 수 있는 IP도 최대 열 개입니다.
- 2026년 6월 25일부터 거래·자산 관리 API의 요청 한도가 포켓 단위로 차감됩니다. 바뀐 그룹은 네 개이고, 시세 조회와 인증 없는 WebSocket 연결은 IP, WebSocket 데이터 요청은 커넥션 단위 그대로입니다. 한도의 크기는 변경 없이 유지됩니다.
- 처리량은 키가 아니라 포켓을 나눠야 늘어납니다. 같은 포켓의 여러 키는 한도를 공유하고, 일시 차단도 포켓 단위로 걸립니다.
- 「포켓 알아보기」 유의사항 문단이 합산이라고 밝힌 항목은 네 가지입니다. 출금 지연제의 출금 한도, 코인빌리기 레벨 산정 거래대금, 에어드랍과 예치금이용료의 지급 대상 수량입니다. 산정은 합산이고 지급은 메인포켓입니다.
- 서브포켓에서 밖으로 나가는 직선 경로는 없습니다. 외부 입출금은 메인포켓만이고, 입출금 관련 권한 네 개도 메인포켓에서만 선택할 수 있으며, 코인빌리기와 스테이킹도 서브포켓에서는 이용할 수 없습니다.
- 되돌릴 수 없는 것과 시한이 붙는 것이 각각 있습니다. 서브포켓은 생성 후 삭제나 이름 수정이 되지 않고, API Key는 발급일로부터 1년간 유효하며 연장할 수 없습니다. 유효기간 문장은 개발자센터가 아니라 고객센터 문서에 있습니다.
한 줄로 줄이면 이렇습니다. 포켓을 나누기 전에 "내가 나누려는 것이 한도인가, 자산인가, 권한인가"부터 정하십시오. 한도와 권한은 포켓을 따라 갈리지만, 지급 대상 수량과 출금 한도는 포켓을 나눠도 하나로 합쳐집니다.
이 글은 업비트가 공개한 개발자센터와 고객센터 문서를 직접 받아 정리한 정보 제공 목적의 글이며, 특정 거래소 이용이나 코인 매매를 권유하지 않습니다. 화면 경로와 수치는 사업자가 바꿀 수 있으므로 실제 이용 전에는 공식 문서를 다시 확인하시기 바랍니다.
확인한 자료: 아래 열여섯 건은 2026년 8월 17일(KST)에 파이썬 표준 라이브러리로 UTF-8 원문을 직접 내려받아 읽었습니다. 개발자센터 열두 건은 마크다운 사본 주소(https://docs.upbit.com/kr/... 에 .md를 붙인 주소)에서 받았습니다. ①「포켓(Pocket)」 reference/pocket-overview.md(문서 갱신 2026-07-30, 6,990바이트) ②「API Key 발급 받기」 docs/api-key.md(2026-07-07, 7,868바이트) ③「요청 수 제한(Rate Limits)」 reference/rate-limits.md(2026-07-20, 19,591바이트) ④「[안내] 거래소 API Rate Limit 적용 단위 변경 (계정 → 포켓)」 changelog/exchange-api-rate-limit-pocket-scope.md(3,411바이트) ⑤「인증」 reference/auth.md(32,948바이트) ⑥「포켓 정보 조회」 reference/list-pockets.md(2026-07-30, 8,042바이트) ⑦「서브포켓 잔고 조회」 reference/get-sub-pocket-balance.md(10,528바이트) ⑧「메인포켓 자산 이전」 reference/universal-transfer.md(2026-07-30, 15,551바이트) ⑨「서브포켓 자산 이전」 reference/transfer.md(2026-07-30, 15,114바이트) ⑩「포켓 잔고 조회」 reference/get-balance.md(9,543바이트) ⑪「포켓별 API Key 목록 조회」 reference/list-pocket-api-keys.md(12,450바이트) ⑫「주문 일괄 취소」 reference/batch-cancel-orders.md(22,365바이트). 고객센터 네 건은 https://support.upbit.com/api/v2/help_center/ko/articles/<번호>.json 형식으로 받았습니다. ⑬「포켓 알아보기」(article 58336071107353, 갱신 2026-08-05) ⑭「업비트 API란 무엇인가요? 어떻게 시작하나요?」(49411138468761, 2026-08-03) ⑮「Open API를 통해 출금하고 싶어요.」(5127257308313, 2026-07-20) ⑯「보안이 걱정돼요. 출금·주문 잠금은 어떻게 설정하나요?」(46995629383321, 2026-08-12).