업비트 포켓 API 7종 — 자산 이전 경로가 2개다

업비트는 2026년 6월 1일 포켓(Pocket) 기능과 전용 API를 내놓았고, 6월 25일에는 거래·자산 관리 API의 Rate Limit 측정 단위를 계정에서 포켓으로 바꿨습니다. 이 변화는 "새 기능이 하나 늘었다"보다 큽니다 — 이미 돌고 있는 봇의 잔고 조회 결과와 요청 한도 계산이 같이 움직였기 때문입니다. 아래는 업비트 개발자 센터의 포켓 API Reference 원문과 변경 공지를 2026년 9월 18일 기준으로 대조해, 봇을 고쳐야 하는 지점만 옮긴 것입니다.

1. 포켓 구조 — 메인 1개 + 서브 최대 5개

포켓은 업비트 계정 안에서 자산을 목적별로 나눠 두는 칸입니다. 계정을 만들면 메인포켓이 1개 주어지고, 여기에 서브포켓을 최대 5개까지 추가할 수 있습니다. 공식 명세의 type 값은 두 가지뿐입니다.

자동매매 관점에서 의미 있는 것은 서브포켓마다 API Key를 따로 발급하고 권한을 다르게 줄 수 있다는 점입니다. 전략 A의 키로는 전략 B의 잔고가 보이지 않고, 전략 A가 한도를 다 써도 전략 B는 멀쩡합니다 — 여러 전략을 한 계정에서 돌릴 때의 "한 봇이 잔고를 다 긁어가는" 구조를 거래소가 막아 주는 셈입니다.

2. 포켓 API 7종 — 경로표

업비트가 신규로 추가했다고 공지한 포켓 API는 7종입니다. 그런데 경로(path) 기준으로는 5개고, 그중 두 개가 POST·GET을 나눠 쓰기 때문에 동작이 7개가 됩니다.

포켓 API는 전부 UUID로 상대를 지목하므로 봇의 첫 호출은 거의 항상 GET /v1/pockets입니다.

GET /v1/pockets

[
  {
    "uuid": "9ca023a5-851b-4fec-9f0a-48cd83c2eaae",
    "name": "단기 트레이딩 계좌",
    "type": "user_spot_trading"
  }
]

돌아오는 필드는 uuid·name·type 셋이고 전부 필수 항목입니다. name은 사용자가 업비트 화면에서 붙인 이름이라 언제든 바뀔 수 있습니다 — 코드에서 포켓을 고를 때 이름으로 매칭하면 사용자가 이름만 바꿔도 봇이 엉뚱한 포켓에 주문을 냅니다. UUID를 설정 파일에 박아 두고 이름은 로그 표시용으로만 쓰는 편이 안전합니다.

3. 자산 이전이 두 갈래인 이유 — from 하나 차이

포켓 간 자산 이전은 같은 일을 하는 엔드포인트가 두 개이고, 어느 쪽을 쓰는지는 내가 든 API Key가 어느 포켓 소속이냐로 결정됩니다.

두 요청의 필수 필드는 to·currency·amount로 동일합니다. 차이는 from입니다.

// 메인포켓 키 — 서브포켓 A에서 서브포켓 B로 직접 옮길 수 있다
POST /v1/pockets/universal_transfers
{
  "from": "9ca023a5-851b-4fec-9f0a-48cd83c2eaae",
  "to":   "1f20b8c4-77aa-4a10-9d31-0c6f3d2e5b19",
  "currency": "KRW",
  "amount": "500000",
  "identifier": "rebal_20260918_01"
}

// 서브포켓 키 — from이 없다. 언제나 내 포켓에서 나간다
POST /v1/pockets/transfers
{
  "to":   "1f20b8c4-77aa-4a10-9d31-0c6f3d2e5b19",
  "currency": "KRW",
  "amount": "500000",
  "identifier": "rebal_20260918_01"
}

universal_transfers에서 from을 생략하면 요청에 쓰인 키가 속한 포켓이 기본값이 됩니다. 즉 메인포켓 키로 from 없이 보내면 메인포켓에서 나갑니다. 공식 문서가 명시하는 메인포켓 키의 이전 가능 범위는 메인→서브, 서브→메인, 서브→서브 세 방향입니다.

4. 이전은 비동기다 — submitted에서 시작한다

가장 조용히 사고가 나는 지점입니다. 포켓 자산 이전은 즉시 반영이 아닙니다. 응답의 state 값은 네 가지입니다.

POST /v1/pockets/transfers  →  200 OK

{
  "uuid": "9ca023a5-851b-4fec-9f0a-48cd83c2eaae",
  "identifier": "rebal_20260918_01",
  "from": "9ca023a5-851b-4fec-9f0a-48cd83c2eaae",
  "to":   "1f20b8c4-77aa-4a10-9d31-0c6f3d2e5b19",
  "state": "submitted",
  "currency": "KRW",
  "amount": "500000",
  "created_at": "2026-05-28T15:17:51+09:00"
}

확인은 목록 조회로 합니다. GET /v1/pockets/transfers에는 uuids[]·identifiers[](각 최대 20개), currency, start_time·end_time, limit(기본 20, 최대 100), 그리고 방향을 거르는 direction(in·out·all)이 있습니다.

5. GET /v1/accounts의 의미가 바뀌었다

기존에 돌던 업비트 봇이 거의 예외 없이 쓰는 호출입니다. 공식 API Reference에서 GET /v1/accounts는 이제 "포켓 잔고 조회"로 분류되어 있고, 요청에 쓰인 키가 속한 포켓의 잔고를 돌려줍니다.

응답 스키마는 예전 그대로입니다 — currency, balance, locked, avg_buy_price, avg_buy_price_modified, unit_currency. 바뀐 것은 필드가 아니라 집계 범위입니다.

GET /v1/accounts        // 이 키가 속한 "포켓"의 잔고

[
  {
    "currency": "BTC",
    "balance": "2.0",
    "locked": "0.0",
    "avg_buy_price": "140000000",
    "avg_buy_price_modified": false,
    "unit_currency": "KRW"
  }
]

6. 권한 9종과 out_of_scope

포켓별 API Key 목록 조회(GET /v1/pockets/api_keys)의 응답에는 access_key·permissions·allowed_ips·created_at·expired_at가 들어 있고, permissions에 올 수 있는 값은 명세상 9종입니다.

권한이 없는 키로 호출하면 out_of_scope 오류가 납니다. GET /v1/pockets가 out_of_scope로 떨어졌다면 인증이 틀린 것이 아니라 그 키에 manage_pockets가 안 붙어 있는 것입니다. JWT 서명이나 query_hash를 뜯어보기 전에 여기부터 보는 편이 빠릅니다 (업비트 REST·WebSocket 정리에 인증 흐름이 있습니다).

7. Rate Limit이 포켓 단위가 됐다 — 키를 늘려도 소용없다

2026년 6월 25일부로 거래·자산 관리(Exchange) REST API와 인증 포함 WebSocket 연결의 Rate Limit 측정 단위가 계정에서 포켓으로 바뀌었습니다. 그룹별 초당 한도 숫자는 그대로이고, 차감 기준만 달라졌습니다.

여기서 실무적으로 가장 중요한 문장은 공식 문서의 이 한 줄입니다 — 같은 포켓의 여러 API Key는 하나의 한도를 공유한다. 처리량을 늘리려고 키를 더 발급하는 것은 아무 효과가 없습니다. 늘려야 하는 것은 포켓입니다. 문서가 드는 예시는 메인포켓 1개 + 서브포켓 5개가 각각 exchange.default 초당 30회를 독립 보유해 계정 합산 최대 초당 180회가 되는 경우입니다(개별 포켓은 그대로 30회).

초과 시 동작도 포켓 기준으로 바뀌었습니다. 429 Too Many Requests는 초당 한도 초과, 418 I'm a teapot은 429가 누적된 일시 차단이고 차단 단위가 IP·포켓·커넥션입니다. 즉 한 서브포켓이 418을 맞아도 다른 포켓은 멀쩡합니다. 정책 위반이 반복되면 차단 시간이 점진적으로 늘어나므로 418에 무작정 재시도를 거는 로직은 상황을 악화시킵니다 (호출 한도 설계 쪽에 백오프 패턴을 정리해 뒀습니다).

8. 정리 — 오늘 봇에서 확인할 다섯 줄

1. GET /v1/accounts를 총자산으로 쓰고 있는가 → 포켓 잔고다. 서브포켓을 만들 계획이면 합산 로직이 필요하다.
2. 이전 후 곧바로 잔고를 읽는가 → state == "done" 확인을 사이에 넣는다.
3. 이전 요청에 identifier가 있는가 → 없으면 재시도가 곧 이중 이전이다.
4. 한도를 자체 카운터로 세는가 → 계정이 아니라 포켓 기준으로 쪼갠다.
5. 처리량을 늘리려고 키를 더 발급했는가 → 같은 포켓이면 효과 0. 포켓을 나눈다.

포켓은 "자산을 나눠 두는 편의 기능"처럼 보이지만, 자동매매 쪽에서는 격리 단위가 하나 생긴 것에 가깝습니다 — 잔고도, 권한도, 요청 한도도, 일시 차단도 포켓 경계에서 끊깁니다.

자주 묻는 것

업비트 포켓(Pocket)이 무엇인가요?

계정 안에서 자산을 목적별로 나누는 단위입니다. 메인포켓 1개에 서브포켓 최대 5개, 명세상 type은 main과 user_spot_trading 둘뿐입니다. 서브포켓은 외부 입출금이 제한되고 manage_pockets는 메인포켓 전용입니다.

포켓 간 자산 이전 API는 어느 것을 써야 하나요?

키가 속한 포켓에 따라 갈립니다. 메인포켓 키는 POST /v1/pockets/universal_transfers, 서브포켓 키는 POST /v1/pockets/transfers입니다. 필수 필드는 둘 다 to·currency·amount이고, 차이는 from입니다 — universal_transfers에만 있고 생략하면 그 키의 포켓이 기본값입니다.

자산을 이전하면 바로 주문에 쓸 수 있나요?

아닙니다. 비동기라 submitted → processing → done/failed로 갑니다. POST가 200이어도 state는 submitted이므로, 목록 조회로 done을 확인한 뒤 주문으로 넘어가되 failed 분기를 두십시오.

API Key를 늘리면 요청 한도가 늘어나나요?

아닙니다. 2026-06-25부터 Exchange API 한도는 포켓 단위이고 같은 포켓의 여러 키는 한도를 공유합니다. 공식 예시는 메인 1 + 서브 5 = 계정 합산 초당 180회 (개별 포켓은 30회 그대로). 시세 조회는 여전히 IP 단위입니다. 한도 정책은 공지 후 바뀌므로 개발자 센터의 현재 문서로 확인하십시오.

기존 봇의 GET /v1/accounts는 그대로 써도 되나요?

호출은 되지만 의미가 달라졌습니다 — 이제 그 키가 속한 포켓의 잔고입니다. 응답 스키마는 그대로라 에러 없이 조용히 적은 잔고를 보고 움직이는 형태로 나타납니다. 계정 전체가 필요하면 GET /v1/pockets + 서브포켓별 GET /v1/pockets/assets를 합산하십시오.