업비트에서 예약주문을 걸어 두고 쓰시는 분이라면, 그것을 프로그램으로 다루려 할 때 한 번은 막힙니다. 공식 문서를 전수로 열어 무엇이 되고 무엇이 안 되는지 확인했습니다.
결론을 먼저 적겠습니다. 예약주문은 만드는 창구에 없고, 상태값으로만 존재합니다. 그리고 그 상태값은 조회 기본값에서 빠져 있습니다.
제약 하나, 주문을 만드는 창구에는 예약주문이 없습니다
주문 생성 문서가 받는 주문 유형은 목록으로 못박혀 있습니다.
| 값 | 뜻 |
|---|---|
| limit | 지정가 |
| price | 시장가 매수, 단가가 아니라 매수 총액을 넘깁니다 |
| market | 시장가 매도 |
| best | 최유리지정가 |
넷입니다. 예약주문이나 조건주문에 해당하는 값이 없고, 감시할 가격을 함께 넘기는 파라미터도 문서에 없습니다. 주문 단가 필드의 설명도 지정가의 단가이거나 시장가 매수의 총액이라고만 적혀 있습니다.
함께 정의된 옵션도 확인했습니다. 주문 체결 조건은 세 가지가 있고, 그중 메이커 주문으로만 생성되게 하는 옵션은 지정가 주문에서만 쓸 수 있으며 자전 거래 체결 방지 옵션과 함께 사용할 수 없다고 적혀 있습니다. 자전 거래 체결 방지 모드는 메이커 주문 취소, 테이커 주문 취소, 수량 감소 세 가지입니다. 호출 제한은 주문 생성이 초당 최대 12회이고 포켓 단위로 측정되며 주문 생성 그룹 안에서 횟수를 공유합니다.
이 목록 어디에도 예약주문을 만드는 자리가 없습니다. 그러니 자동화를 계획할 때 예약주문을 거는 단계는 사람이 앱이나 웹에서 하는 것으로 두고 설계해야 합니다. 문서는 호출 제한에 대해 요청 처리량을 보장하는 기준이 아니며 트래픽 상황이나 서비스 안정성 확보 필요에 따라 제한되거나 조정될 수 있다는 점도 함께 밝히고 있습니다.
제약 둘, 상태값은 있는데 조회 기본값에서 빠집니다
그런데 같은 문서의 다른 자리에는 예약주문이 분명히 있습니다. 주문 상태 정의입니다.
| 상태 | 뜻 | 분류 |
|---|---|---|
| wait | 체결 대기 | 대기 주문 |
| watch | 예약 주문 대기 | 대기 주문 |
| done | 체결 완료 | 완료 주문 |
| cancel | 주문 취소 | 완료 주문 |
문서는 대기 주문 상태를 두 값으로 묶어 정의합니다. 체결 대기와 예약 주문 대기입니다. 그러니 조회는 됩니다.
문제는 기본값입니다. 대기 주문 목록 조회의 상태 파라미터 설명은 사용 가능한 값이 체결 대기와 예약 주문 대기이며 미지정 시 기본값은 체결 대기라고 적습니다. 배열로 넘기는 파라미터도 미지정 시 기본값이 체결 대기 하나입니다.
즉 상태를 넣지 않고 부르면 예약주문은 응답에 들어오지 않습니다. 문서에 실린 예시 요청이 두 값을 함께 넘기는 형태로 적혀 있는 것도 이 때문입니다.
이 자리가 만드는 사고
여기서 생기는 문제는 조용합니다. 응답이 오류를 내지 않고 정상으로 돌아오기 때문입니다.
- 예약주문에 묶인 자산만큼 사용 가능 금액이 줄어 있는데 대기 주문 목록에는 그 주문이 없습니다.
- 잔고와 주문을 맞춰 보는 계산이 어긋나고, 원인을 다른 곳에서 찾게 됩니다.
- 이미 걸어 둔 예약주문을 모르고 같은 방향의 주문을 한 번 더 걸 수 있습니다.
처방은 간단합니다. 조회 요청에 두 상태를 모두 넣는 것입니다. 주문 유형별 성질과 체결 조건은 코인 지정가와 시장가 주문의 차이 쪽에 따로 정리해 두었습니다.
상태가 옮겨 가는 순간
상태값 정의를 다시 보면 설계가 읽힙니다. 문서는 네 상태를 대기와 완료 두 묶음으로 나누고, 조회 창구도 그에 맞춰 나뉘어 있습니다. 대기 주문 목록을 받는 창구와 완료 주문을 받는 창구가 별개입니다.
예약주문 하나가 지나가는 경로를 그리면 이렇게 됩니다. 처음에는 예약 주문 대기입니다. 감시 가격에 닿으면 주문이 접수되어 체결 대기로 옮겨 갑니다. 여기까지는 대기 주문 창구에서 보입니다. 체결이 끝나거나 취소되면 체결 완료 또는 주문 취소가 되고, 그때부터는 완료 주문 창구에서 봐야 합니다.
폴링으로 상태를 따라가는 도구를 만든다면 이 경로가 설계 요건이 됩니다. 대기 창구는 두 상태를 함께 요청해야 하고, 목록에서 사라진 주문은 실패가 아니라 완료 묶음으로 옮겨 간 것일 수 있으므로 완료 창구를 한 번 더 확인해야 합니다. 이 구분을 놓치면 정상적으로 체결된 주문을 사라진 주문으로 오해하게 됩니다.
제약 셋, 서버 점검 때 처리가 다릅니다
세 번째 제약은 문서가 아니라 공지에 있습니다. 업비트가 개발자센터에 올린 서버 점검 안내의 문구입니다.
점검 시간 동안 모든 마켓의 주문은 유지되며, 점검 완료 후 취소 조건에 해당하지 않는 주문은 자동 재개된다고 적혀 있습니다. 그리고 취소 조건을 가격으로 특정합니다.
- 점검 시작 시각 이전의 마지막 체결가보다 높은 가격의 매수 주문
- 점검 시작 시각 이전의 마지막 체결가보다 낮은 가격의 매도 주문
두 조건이 가리키는 것은 같은 성질의 주문입니다. 재개 직후 즉시 체결될 수 있는 방향의 주문입니다. 점검 중 시세가 크게 움직였다면 재개 순간에 불리하게 체결될 수 있으니 미리 걷어 내는 조치로 읽힙니다.
예약주문에 대해서는 같은 공지가 따로 적습니다. 예약 주문은 취소되지 않는다는 것과, 점검 기간 동안 발생한 시세 변화로 인해 점검 종료 이후 예약 주문이 감시 가격에 도달하여 접수될 수 있으니 사전에 확인하라는 것입니다.
여기서 용어 하나가 확인됩니다. 예약주문의 발동 기준을 업비트는 감시 가격이라고 부릅니다. 곧 예약주문은 가격을 감시하다가 조건에 닿으면 그때 주문을 접수하는 구조입니다. 점검 중에는 감시가 멈추고 시세만 움직이므로, 재개 시점에 조건을 이미 지나쳐 있을 수 있습니다.
자주 묻는 질문과 공지가 어긋나 보이는 자리
업비트 자주 묻는 질문에는 미체결 주문이 직접 취소하기 전까지 유지되며, 서버 점검 시 자산 보호를 위해 일부의 경우 주문 취소를 진행한다고 적혀 있습니다. 반면 점검 공지는 예약주문을 취소하지 않는다고 적습니다.
두 문서가 다투는 것이 아닙니다. 대상이 다릅니다.
| 주문 종류 | 점검 시 처리 |
|---|---|
| 일반 미체결 주문 중 가격 조건에 해당 | 취소 |
| 일반 미체결 주문 중 조건에 해당하지 않음 | 유지 후 자동 재개 |
| 예약주문 | 취소하지 않음, 재개 후 감시 가격 도달 시 접수 |
같은 공지가 덧붙이는 항목도 실무에 영향을 줍니다. 점검 시간 내에 예정된 코인 모으기 주문이 있으면 실패가 발생할 수 있다는 안내와, 점검 시간 동안 스테이킹 서비스 이용이 불가하다는 안내입니다. 자동으로 돌아가게 걸어 둔 것들이 점검 창에서 서로 다르게 취급된다는 뜻입니다.
실무 순서
정리하면 이렇습니다.
- 예약주문은 사람이 걸고, 프로그램은 확인만 하는 것으로 설계합니다. 만드는 창구에 그 유형이 없습니다.
- 대기 주문을 조회할 때 두 상태를 모두 넣습니다. 기본값이 체결 대기 하나라 예약주문이 조용히 빠집니다.
- 점검 공지가 뜨면 예약주문을 직접 확인합니다. 취소되지 않고 유지되므로, 점검 중 시세가 움직였다면 재개 직후 접수될 수 있습니다.
- 가격 조건에 걸린 일반 미체결 주문은 점검 후 사라져 있을 수 있습니다. 재개 뒤 주문 목록을 다시 받아 대조합니다.
손절과 익절 주문을 어떻게 나눠 걸지에 대한 정리는 손절과 익절 주문 정리 쪽에 있습니다.
이 글은 2026년 9월 19일에 업비트 개발자센터 문서와 공지, 자주 묻는 질문을 직접 열어 확인한 내용입니다. 문서는 갱신될 수 있으므로 자동화를 구현하기 전에 같은 페이지를 다시 확인하시기 바랍니다. 정보 제공 목적이며 매매 권유가 아닙니다. 가상자산은 변동성이 크고 원금 손실이 발생할 수 있습니다.