---
updatedAt: 2026-07-09T08:18:59.000Z
---
Fetch the complete documentation index at: https://apidocs.bithumb.com/llms.txt. Use this file to discover all available pages before exploring further. Append .md to any documentation page URL to get its markdown version.
# 종료 주문 목록 조회
처리 완료(done) 또는 취소(cancel)된 주문 목록을 조회합니다. 조회 기간은 최대 7일로 제한됩니다.
[주문 리스트 조회: v1/orders](doc:주문-리스트-조회)의 `state=done/cancel` 조회에 해당하며, 조회 성능이 개선되었습니다.
#### 조회 규칙
* `state`와 `states`는 동시에 사용할 수 없으며, 둘 다 전달하지 않은 경우 종료된 주문 목록(`done`, `cancel`) 을 전부 조회합니다.
* `start_time`과 `end_time`의 조회 범위는 최대 7일이며, 미입력 시 아래와 같이 자동 설정됩니다.
| `start_time` | `end_time` | 동작 |
| ------------ | ---------- | --------------------------------------- |
| 미입력 | 미입력 | `end_time` = 현재, `start_time` = 현재 - 7일 |
| 입력 | 미입력 | `end_time` = `start_time` + 7일 |
| 미입력 | 입력 | `start_time` = `end_time` - 7일 |
| 입력 | 입력 | 입력한 범위로 조회. 범위가 7일 초과 시 에러 |
#### 조회되지 않는 주문
* **예약 상태(`watch`)에서 취소된 자동주문은 조회할 수 없습니다.** 자동주문은 감시가 도달 후 `wait`로 전환되어 체결(`done`) 혹은 취소(`cancel`)된 경우에만 조회됩니다.
# OpenAPI definition
```json
{
"openapi": "3.1.0",
"info": {
"title": "bithumb_api_v2",
"version": "2.0.0"
},
"servers": [
{
"url": "https://api.bithumb.com/v2"
}
],
"security": [
{}
],
"paths": {
"/orders/history": {
"get": {
"summary": "종료 주문 목록 조회",
"description": "처리 완료(done) 또는 취소(cancel)된 주문 목록을 조회합니다. 조회 기간은 최대 7일로 제한됩니다.",
"operationId": "종료-주문-목록-조회",
"parameters": [
{
"name": "Authorization",
"in": "header",
"description": "Authorization token (JWT)",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "market",
"in": "query",
"description": "거래 대상 페어의 고유 심볼\n\n예시) KRW-BTC",
"schema": {
"type": "string"
}
},
{
"name": "state",
"in": "query",
"description": "주문 상태\n- `done`: 주문 처리 완료\n- `cancel`: 주문 취소",
"schema": {
"type": "string",
"enum": [
"done",
"cancel"
]
}
},
{
"name": "states",
"in": "query",
"description": "주문 상태 목록\n- `done`: 주문 처리 완료\n- `cancel`: 주문 취소",
"style": "form",
"explode": true,
"schema": {
"type": "array",
"items": {
"type": "string",
"enum": [
"done",
"cancel"
]
}
}
},
{
"name": "start_time",
"in": "query",
"description": "조회 시작 시각. 지원 형식:\n- Unix Timestamp 밀리초(권장): `1775401200000`\n- ISO 8601 with timezone: `2026-04-06T00:00:00+09:00`\n (URL에서 `+`는 `%2B`로 인코딩)",
"schema": {
"type": "string"
}
},
{
"name": "end_time",
"in": "query",
"description": "조회 종료 시각. `start_time`과 동일한 형식.\n`start_time` 이상이어야 하며, 조회 기간은 최대 7일.",
"schema": {
"type": "string"
}
},
{
"name": "limit",
"in": "query",
"description": "조회할 주문 개수(max 1000)",
"schema": {
"type": "integer",
"default": 100,
"minimum": 1,
"maximum": 1000
}
},
{
"name": "order_by",
"in": "query",
"description": "조회 결과 정렬 방식\n- `asc`: 오래된 주문 순\n- `desc`: 최신 주문 순(default)",
"schema": {
"type": "string",
"enum": [
"asc",
"desc"
],
"default": "desc"
}
},
{
"name": "next_key",
"in": "query",
"description": "이전 응답에서 반환된 `next_key` 값",
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "200",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"order_id": {
"type": "string",
"description": "주문의 고유 ID"
},
"side": {
"type": "string",
"description": "주문 종류\n- `bid`: 매수\n- `ask`: 매도",
"enum": [
"bid",
"ask"
]
},
"order_type": {
"type": "string",
"description": "주문 유형\n- `limit`: 지정가\n- `price`: 시장가(매수)\n- `market`: 시장가(매도)\n- `best`: 최유리 지정가(현재 원화 마켓에서만 지원)",
"enum": [
"limit",
"price",
"market",
"best"
]
},
"price": {
"type": "string",
"description": "주문 가격"
},
"state": {
"type": "string",
"description": "주문 상태\n- `done`: 주문 처리 완료\n- `cancel`: 주문 취소",
"enum": [
"done",
"cancel"
]
},
"market": {
"type": "string",
"description": "거래 대상 페어의 고유 심볼\n\n예시) KRW-BTC"
},
"created_at": {
"type": "string",
"description": "주문 생성 시각",
"format": "date-time"
},
"volume": {
"type": "string",
"description": "주문 수량"
},
"remaining_volume": {
"type": "string",
"description": "미체결 잔여 수량"
},
"reserved_fee": {
"type": "string",
"description": "예약된 수수료. 매수 주문은 기준통화 단위, 매도 주문은 0.\n\n예시) KRW-DOGE는 KRW, BTC-DOGE는 BTC"
},
"remaining_fee": {
"type": "string",
"description": "미사용 예약 수수료. 매수 주문은 기준통화 단위, 매도 주문은 0.\n\n예시) KRW-DOGE는 KRW, BTC-DOGE는 BTC"
},
"paid_fee": {
"type": "string",
"description": "체결 수수료 누적 합계. 기준통화 단위.\n\n예시) KRW-DOGE는 KRW, BTC-DOGE는 BTC"
},
"locked": {
"type": "string",
"description": "거래에 사용 중인 금액. 매수 주문은 기준통화 금액, 매도 주문은 주문통화 수량.\n\n예시) KRW-DOGE 매수는 KRW, 매도는 DOGE"
},
"executed_volume": {
"type": "string",
"description": "체결된 수량"
},
"executed_funds": {
"type": "string",
"description": "체결된 총 금액"
},
"trades_count": {
"type": "integer",
"description": "해당 주문에 걸린 체결 수"
},
"client_order_id": {
"type": "string",
"description": "서버에서 부여하는 주문 ID(`order_id`)와 별도로 주문 생성 시 사용자가 직접 지정한 고유 ID. \n\n해당 주문에 `client_order_id` 존재하는 경우 반환"
},
"stp_type": {
"type": "string",
"description": "자전거래 방지 처리 유형\n- `cancel_taker`: 자전거래 감지 시 taker(신규 주문) 취소",
"enum": [
"cancel_taker"
],
"default": "cancel_taker"
},
"time_in_force": {
"type": "string",
"enum": [
"ioc",
"fok",
"post_only"
],
"description": "주문 처리 조건\n- `ioc`: 즉시 체결 가능한 수량만 체결하고, 나머지는 취소합니다.\n- `fok`: 전체 수량이 즉시 체결 가능할 때만 체결하고, 아니면 전량 취소합니다.\n- `post_only`: 호가창에 등록되는 maker 주문일 때만 허용하며, 즉시 체결될 수 있는 주문일 경우 취소합니다."
},
"cancel_type": {
"type": "string",
"description": "취소 유형\n- `stp_cancel`: 자전거래 감지에 의한 취소\n- `user_cancel`: 사용자 취소\n- `admin_cancel`: 관리자 취소\n- `tif_cancel`: 주문 처리 조건에 의한 취소",
"enum": [
"stp_cancel",
"user_cancel",
"admin_cancel",
"tif_cancel"
]
},
"canceling_order_id": {
"type": "string",
"description": "`cancel_type`이 `stp_cancel`인 경우, 해당 주문을 취소시킨 반대 주문의 고유 ID"
}
},
"required": [
"order_id",
"side",
"order_type",
"state",
"market",
"volume",
"remaining_volume",
"reserved_fee",
"remaining_fee",
"paid_fee",
"locked",
"executed_volume",
"executed_funds",
"trades_count"
]
}
},
"has_next": {
"type": "boolean",
"description": "다음 페이지 존재 여부"
},
"next_key": {
"type": "string",
"nullable": true,
"description": "다음 페이지 조회 시 `next_key` 파라미터에 전달합니다. 다음 페이지가 없으면 null"
}
},
"required": [
"data",
"has_next",
"next_key"
]
},
"examples": {
"Result": {
"value": {
"data": [
{
"order_id": "C0101000007410714029",
"side": "bid",
"order_type": "limit",
"price": "50000000.0",
"state": "done",
"market": "KRW-BTC",
"created_at": "2026-04-06T12:00:00.000+09:00",
"volume": "0.001",
"remaining_volume": "0.0",
"reserved_fee": "25.0",
"remaining_fee": "0.0",
"paid_fee": "25.0",
"locked": "0.0",
"executed_volume": "0.001",
"executed_funds": "50000.0",
"trades_count": 1,
"client_order_id": "my-order-001",
"stp_type": "cancel_taker"
}
],
"has_next": true,
"next_key": "eyJvcmRlckR0bUVwb2NoIjoxNzc1NTE2MDAwMDAwfQ=="
}
}
}
}
}
},
"400": {
"description": "400",
"content": {
"application/json": {
"examples": {
"bad_request": {
"summary": "bad_request",
"value": {
"error": {
"name": "bad_request",
"message": "state and states[] cannot be used together"
}
}
}
},
"schema": {
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"name": {
"type": "string",
"example": "bad_request",
"description": "에러명"
},
"message": {
"type": "string",
"example": "error message",
"description": "에러 메시지"
}
}
}
},
"required": [
"error"
]
}
}
}
}
},
"deprecated": false,
"x-readme": {
"code-samples": [
{
"language": "javascript",
"code": " const jwt = require('jsonwebtoken');\n const { v4: uuidv4 } = require('uuid');\n const crypto = require('crypto');\n const axios = require('axios')\n\n const accessKey = '발급받은 API KEY'\n const secretKey = '발급받은 SECRET KEY'\n const apiUrl = 'https://api.bithumb.com'\n\n // Set API parameters\n\n // [Option 1] state 단건 조회 (epoch millis 방식)\n var params = { state: 'done', start_time: '1775430000000', end_time: '1775516399000', limit: '10', order_by: 'desc' }\n var states = []\n\n // [Option 2] states[] 복수 조회 (ISO 8601 방식) - Option 1 주석 처리 후 사용\n // var params = { start_time: '2026-04-06T00:00:00+09:00', end_time: '2026-04-06T23:59:59+09:00', limit: '10', order_by: 'desc' }\n // var states = ['done', 'cancel']\n\n // market 필터 추가 시\n // params.market = 'KRW-BTC'\n\n // For JWT hash: use raw values (no URL encoding)\n var statesQuery = states.map(s => `states[]=${s}`).join('&')\n var queryRaw = Object.entries(params).map(([k, v]) => `${k}=${v}`).join('&')\n if (statesQuery) queryRaw = queryRaw + '&' + statesQuery\n\n // For URL: use encoded values\n var queryUrl = new URLSearchParams(params).toString()\n if (statesQuery) queryUrl = queryUrl + '&' + statesQuery\n\n // Generate access token\n const alg = 'SHA512'\n const hash = crypto.createHash(alg)\n const queryHash = hash.update(queryRaw, 'utf-8').digest('hex')\n const payload = {\n access_key: accessKey,\n nonce: uuidv4(),\n timestamp: Date.now(),\n query_hash: queryHash,\n query_hash_alg: alg\n }\n const jwtToken = jwt.sign(payload, secretKey)\n const config = {\n headers: {\n Authorization: `Bearer ${jwtToken}`\n }\n }\n\n // Call API\n axios.get(apiUrl + '/v2/orders/history?' + queryUrl, config)\n .then((response) => {\n // handle to success\n console.log('status: ', response.status)\n console.log('data: ', response.data)\n })\n .catch((error) => {\n // handle to fail\n console.log(error.response.status)\n console.log(error.response.data)\n })"
},
{
"language": "python",
"code": " # Python 3\n # pip3 installl pyJwt\n import jwt\n import uuid\n import hashlib\n import time\n from urllib.parse import urlencode\n import requests\n\n accessKey = '발급받은 API KEY'\n secretKey = '발급받은 SECRET KEY'\n apiUrl = 'https://api.bithumb.com'\n\n # Set API parameters\n\n # [Option 1] state 단건 조회 (epoch millis 방식)\n param = dict( state='done', start_time='1775430000000', end_time='1775516399000', limit=10, order_by='desc' )\n states = []\n\n # [Option 2] states[] 복수 조회 (ISO 8601 방식) - Option 1 주석 처리 후 사용\n # param = dict( start_time='2026-04-06T00:00:00+09:00', end_time='2026-04-06T23:59:59+09:00', limit=10, order_by='desc' )\n # states = ['done', 'cancel']\n\n # market 필터 추가 시\n # param['market'] = 'KRW-BTC'\n\n # For JWT hash: use raw values (no URL encoding)\n states_query = '&'.join([f'states[]={s}' for s in states])\n query_string = '&'.join([f'{k}={v}' for k, v in param.items()])\n if states_query:\n query_string = query_string + '&' + states_query\n\n # For URL: use encoded values\n query = urlencode(param)\n if states_query:\n query = query + '&' + states_query\n\n # Generate access token\n hash = hashlib.sha512()\n hash.update(query_string.encode())\n query_hash = hash.hexdigest()\n payload = {\n 'access_key': accessKey,\n 'nonce': str(uuid.uuid4()),\n 'timestamp': round(time.time() * 1000),\n 'query_hash': query_hash,\n 'query_hash_alg': 'SHA512',\n }\n jwt_token = jwt.encode(payload, secretKey)\n authorization_token = 'Bearer {}'.format(jwt_token)\n headers = {\n 'Authorization': authorization_token\n }\n\n try:\n # Call API\n response = requests.get(apiUrl + '/v2/orders/history?' + query, headers=headers)\n # handle to success or fail\n print(response.status_code)\n print(response.json())\n except Exception as err:\n # handle exception\n print(err)"
},
{
"language": "java",
"code": " package com.example.sample;\n\n // https://mvnrepository.com/artifact/com.auth0/java-jwt\n import com.auth0.jwt.JWT;\n import com.auth0.jwt.algorithms.Algorithm;\n // https://mvnrepository.com/artifact/org.apache.httpcomponents/httpclient\n import org.apache.http.NameValuePair;\n import org.apache.http.client.methods.CloseableHttpResponse;\n import org.apache.http.client.methods.HttpGet;\n import org.apache.http.client.utils.URLEncodedUtils;\n import org.apache.http.impl.client.CloseableHttpClient;\n import org.apache.http.impl.client.HttpClients;\n import org.apache.http.message.BasicNameValuePair;\n import org.apache.http.util.EntityUtils;\n\n import java.math.BigInteger;\n import java.nio.charset.StandardCharsets;\n import java.security.MessageDigest;\n import java.security.NoSuchAlgorithmException;\n import java.util.ArrayList;\n import java.util.List;\n import java.util.UUID;\n import java.util.stream.Collectors;\n\n public class GETOrdersHistory {\n\n public static void main(String[] args) throws NoSuchAlgorithmException {\n String accessKey = \"발급받은 API KEY\";\n String secretKey = \"발급받은 SECRET KEY\";\n String apiUrl = \"https://api.bithumb.com\";\n\n // Set API parameters\n // [Option 1] state 단건 조회 (epoch millis 방식)\n List queryParams = new ArrayList<>();\n queryParams.add(new BasicNameValuePair(\"state\", \"done\"));\n queryParams.add(new BasicNameValuePair(\"start_time\", \"1775430000000\"));\n queryParams.add(new BasicNameValuePair(\"end_time\", \"1775516399000\"));\n queryParams.add(new BasicNameValuePair(\"limit\", \"10\"));\n queryParams.add(new BasicNameValuePair(\"order_by\", \"desc\"));\n List states = new ArrayList<>();\n\n // market 필터 추가 시\n // queryParams.add(new BasicNameValuePair(\"market\", \"KRW-BTC\"));\n\n // [Option 2] states[] 복수 조회 시 - Option 1의 states 선언 주석 처리 후 사용\n // List states = List.of(\"done\", \"cancel\");\n\n // For JWT hash: use raw values (no URL encoding)\n String statesQuery = states.stream().map(s -> \"states[]=\" + s).collect(Collectors.joining(\"&\"));\n String queryString = queryParams.stream()\n .map(p -> p.getName() + \"=\" + p.getValue())\n .collect(Collectors.joining(\"&\"));\n if (!statesQuery.isEmpty()) {\n queryString = queryString + \"&\" + statesQuery;\n }\n\n // For URL: use encoded values\n String query = URLEncodedUtils.format(queryParams, StandardCharsets.UTF_8);\n if (!statesQuery.isEmpty()) {\n query = query + \"&\" + statesQuery;\n }\n\n // Generate access token\n MessageDigest md = MessageDigest.getInstance(\"SHA-512\");\n md.update(queryString.getBytes(StandardCharsets.UTF_8));\n String queryHash = String.format(\"%0128x\", new BigInteger(1, md.digest()));\n Algorithm algorithm = Algorithm.HMAC256(secretKey);\n String jwtToken = JWT.create()\n .withClaim(\"access_key\", accessKey)\n .withClaim(\"nonce\", UUID.randomUUID().toString())\n .withClaim(\"timestamp\", System.currentTimeMillis())\n .withClaim(\"query_hash\", queryHash)\n .withClaim(\"query_hash_alg\", \"SHA512\")\n .sign(algorithm);\n String authenticationToken = \"Bearer \" + jwtToken;\n\n // Call API\n final HttpGet httpRequest = new HttpGet(apiUrl + \"/v2/orders/history?\" + query);\n httpRequest.addHeader(\"Authorization\", authenticationToken);\n\n try (CloseableHttpClient client = HttpClients.createDefault();\n CloseableHttpResponse response = client.execute(httpRequest)) {\n // handle to response\n int httpStatus = response.getStatusLine().getStatusCode();\n String responseBody = EntityUtils.toString(response.getEntity(), StandardCharsets.UTF_8);\n System.out.println(httpStatus);\n System.out.println(responseBody);\n } catch (Exception e) {\n throw new RuntimeException(e);\n }\n }\n }"
}
],
"samples-languages": [
"javascript",
"python",
"java"
]
}
}
}
},
"x-readme": {
"headers": [],
"explorer-enabled": false,
"proxy-enabled": true
},
"x-readme-fauxas": true
}
```