# REST API 전체 엔드포인트

기본 주소는 `https://api.btxpro.co.kr`입니다. 현재 HTTP API **25개 작업**을 제공합니다. 경로에 표시된 `/v1`을 포함해 요청하세요. `/health`와 `/ready`는 버전 경로 밖에 있습니다.

[API 레퍼런스](/api-docs/reference.md)에서 전체 요청·응답 모델을 볼 수 있습니다. [WebSocket 연결과 메시지](/api-docs/websocket/overview.md)는 별도 가이드를 확인하세요.

## 시스템

| 메서드 | 경로 | 인증 | 설명 |
| --- | --- | --- | --- |
| GET | [`/health`](#health) | 공개 | 서비스 상태 |
| GET | [`/ready`](#readiness) | 공개 | 서비스 준비 상태 |
| GET | [`/v1/time`](#gettime) | 공개 | 서버 시간 |

### 서비스 상태 {#health}

`GET https://api.btxpro.co.kr/health`

인증: **공개**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | Service is alive |

### 서비스 준비 상태 {#readiness}

`GET https://api.btxpro.co.kr/ready`

인증: **공개**

Checks database access plus the Core and engine connector wiring required by the external trading API.

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |
| 503 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### 서버 시간 {#gettime}

`GET https://api.btxpro.co.kr/v1/time`

인증: **공개**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

## 공개 시세

| 메서드 | 경로 | 인증 | 설명 |
| --- | --- | --- | --- |
| GET | [`/v1/currencies`](#listcurrencies) | 공개 | 통화 목록 |
| GET | [`/v1/markets`](#listmarkets) | 공개 | 마켓 목록 |
| GET | [`/v1/markets/{symbol}`](#getmarket) | 공개 | 마켓 상세 |
| GET | [`/v1/market/ticker`](#getticker) | 공개 | 현재 시세 |
| GET | [`/v1/market/orderbook`](#getorderbook) | 공개 | 호가 |
| GET | [`/v1/market/trades`](#gettrades) | 공개 | 최근 체결 |
| GET | [`/v1/market/candles`](#getcandles) | 공개 | 캔들 |

### 통화 목록 {#listcurrencies}

`GET https://api.btxpro.co.kr/v1/currencies`

인증: **공개**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 마켓 목록 {#listmarkets}

`GET https://api.btxpro.co.kr/v1/markets`

인증: **공개**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 마켓 상세 {#getmarket}

`GET https://api.btxpro.co.kr/v1/markets/{symbol}`

인증: **공개**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `symbol` | path | 예 | string |  |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 현재 시세 {#getticker}

`GET https://api.btxpro.co.kr/v1/market/ticker`

인증: **공개**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `symbol` | query | 아니요 | string |  |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 호가 {#getorderbook}

`GET https://api.btxpro.co.kr/v1/market/orderbook`

인증: **공개**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `symbol` | query | 예 | string |  |
| `tick` | query | 아니요 | integer | default: 0; minimum: 0; maximum: 4 |
| `limit` | query | 아니요 | integer | default: 100; minimum: 1; maximum: 1000 |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 최근 체결 {#gettrades}

`GET https://api.btxpro.co.kr/v1/market/trades`

인증: **공개**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `symbol` | query | 예 | string |  |
| `limit` | query | 아니요 | integer | default: 100; minimum: 1; maximum: 1000 |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 캔들 {#getcandles}

`GET https://api.btxpro.co.kr/v1/market/candles`

인증: **공개**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `symbol` | query | 예 | string |  |
| `interval` | query | 아니요 | string | 허용값: "1m", "5m", "10m", "15m", "30m", "1h", "4h", "1d", "1w"; default: "1h" |
| `limit` | query | 아니요 | integer | default: 500; minimum: 1; maximum: 1000 |
| `startTime` | query | 아니요 | integer | minimum: 0; format: "int64" |
| `endTime` | query | 아니요 | integer | minimum: 1; format: "int64" |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

## Feed

| 메서드 | 경로 | 인증 | 설명 |
| --- | --- | --- | --- |
| GET | [`/v1/feed/home`](#getfeedhome) | 공개 | Feed 홈 |
| GET | [`/v1/feed/categories`](#listfeedcategories) | 공개 | Feed 카테고리 목록 |
| GET | [`/v1/feed/articles`](#listfeedarticles) | 공개 | Feed 글 목록과 검색 |
| GET | [`/v1/feed/articles/{feedArticleId}`](#getfeedarticle) | 공개 | Feed 글 상세 |
| POST | [`/v1/feed/articles/{feedArticleId}/view`](#incrementfeedarticleview) | 공개 | Feed 조회수 증가 |

### Feed 홈 {#getfeedhome}

`GET https://api.btxpro.co.kr/v1/feed/home`

인증: **공개**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |
| 500 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 503 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### Feed 카테고리 목록 {#listfeedcategories}

`GET https://api.btxpro.co.kr/v1/feed/categories`

인증: **공개**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |
| 500 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 503 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### Feed 글 목록과 검색 {#listfeedarticles}

`GET https://api.btxpro.co.kr/v1/feed/articles`

인증: **공개**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `categoryId` | query | 아니요 | string | pattern: "^[1-9][0-9]*$" |
| `authorName` | query | 아니요 | string | minLength: 1; maxLength: 80 |
| `q` | query | 아니요 | string | Search title, summary, and Markdown body. Whitespace is normalized and each term is matched as a substring; an article must contain every term. Terms shorter than 2 characters and boolean operator characters (+-><()~*"@) are ignored, and a query left with no searchable term is rejected. Search results are globally limited and ordered by title match, summary-only match, then body-only match; sort and cursor cannot be combined with q. minLength: 2; maxLength: 80 |
| `sort` | query | 아니요 | string | Cannot be combined with q. 허용값: "latest", "popular"; default: "latest" |
| `limit` | query | 아니요 | integer | default: 20; minimum: 1; maximum: 100 |
| `cursor` | query | 아니요 | string | Opaque keyset cursor returned as nextCursor. A cursor is bound to its latest or popular sort and cannot be combined with q. minLength: 1; maxLength: 512 |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |
| 400 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 500 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 503 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### Feed 글 상세 {#getfeedarticle}

`GET https://api.btxpro.co.kr/v1/feed/articles/{feedArticleId}`

인증: **공개**

The response supplies canonicalKey and canonicalPath. The slug is presentation metadata and is not used for database lookup.

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `feedArticleId` | path | 예 | string | pattern: "^[1-9][0-9]*$" |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |
| 400 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 404 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 500 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 503 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### Feed 조회수 증가 {#incrementfeedarticleview}

`POST https://api.btxpro.co.kr/v1/feed/articles/{feedArticleId}/view`

인증: **공개**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `feedArticleId` | path | 예 | string | pattern: "^[1-9][0-9]*$" |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |
| 400 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 404 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 500 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 503 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

## 계정과 지갑

| 메서드 | 경로 | 인증 | 설명 |
| --- | --- | --- | --- |
| GET | [`/v1/account`](#getaccount) | 서명된 키 | 계정과 API 키 권한 |
| GET | [`/v1/wallets`](#listwallets) | 서명 + read | 지갑 목록 |
| GET | [`/v1/balances`](#listbalances) | 서명 + read | 잔고 목록 |

### 계정과 API 키 권한 {#getaccount}

`GET https://api.btxpro.co.kr/v1/account`

인증: **서명된 키**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 지갑 목록 {#listwallets}

`GET https://api.btxpro.co.kr/v1/wallets`

인증: **서명 + read**

파라미터가 없습니다.

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

### 잔고 목록 {#listbalances}

`GET https://api.btxpro.co.kr/v1/balances`

인증: **서명 + read**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `walletId` | query | 아니요 | integer | minimum: 1; maximum: 255 |
| `currency` | query | 아니요 | string |  |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |

## 주문과 체결

| 메서드 | 경로 | 인증 | 설명 |
| --- | --- | --- | --- |
| POST | [`/v1/orders`](#createorder) | 서명 + trade | 지정가 주문 생성 |
| DELETE | [`/v1/orders`](#cancelorders) | 서명 + trade | 지갑의 주문 일괄 취소 |
| GET | [`/v1/orders/open`](#listopenorders) | 서명 + read | 미체결 주문 목록 |
| GET | [`/v1/orders/history`](#listorderhistory) | 서명 + read | 주문 이력 |
| GET | [`/v1/orders/{orderId}`](#getorder) | 서명 + read | 주문 상세 |
| DELETE | [`/v1/orders/{orderId}`](#cancelorder) | 서명 + trade | 주문 취소 |
| GET | [`/v1/fills`](#listfills) | 서명 + read | 체결 이력 |

### 지정가 주문 생성 {#createorder}

`POST https://api.btxpro.co.kr/v1/orders`

인증: **서명 + trade**

The gateway correlates the engine result through a shared in-memory dispatcher and waits up to 10 seconds for this REST request. Market orders, post-only, quote quantity, and non-GTC time-in-force values are reserved for future support.

파라미터가 없습니다.

요청 본문: [CreateOrderRequest](/api-docs/generated/schemas.md#schema-createorderrequest)

| 필드 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- |
| `symbol` | 예 | string |  |
| `walletId` | 예 | integer | Required account-local visible spot-trading wallet ID from GET /v1/wallets; not a blockchain address or walletNumber. The server never chooses a default wallet. minimum: 21; maximum: 39 |
| `side` | 예 | string | 허용값: "buy", "sell" |
| `type` | 예 | string | 허용값: "limit" |
| `timeInForce` | 아니요 | string | 허용값: "GTC"; default: "GTC" |
| `quantity` | 예 | string |  |
| `quoteQuantity` | 아니요 | string | Reserved for future support. |
| `price` | 예 | string |  |
| `postOnly` | 아니요 | boolean | Reserved for future support. |

| HTTP | 응답 |
| --- | --- |
| 200 | [OrderEnvelope](/api-docs/generated/schemas.md#schema-orderenvelope) |
| 422 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 504 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### 지갑의 주문 일괄 취소 {#cancelorders}

`DELETE https://api.btxpro.co.kr/v1/orders`

인증: **서명 + trade**

Matching cancels run with up to 16 concurrent engine commands, preserve selection order in the response, and share one 10-second deadline.

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `walletId` | query | 예 | integer | minimum: 1; maximum: 255 |
| `symbol` | query | 아니요 | string |  |
| `limit` | query | 아니요 | integer | default: 100; minimum: 1; maximum: 1000 |

| HTTP | 응답 |
| --- | --- |
| 200 | [CancelOrderListEnvelope](/api-docs/generated/schemas.md#schema-cancelorderlistenvelope) |
| 504 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### 미체결 주문 목록 {#listopenorders}

`GET https://api.btxpro.co.kr/v1/orders/open`

인증: **서명 + read**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `walletId` | query | 아니요 | integer | minimum: 1; maximum: 255 |
| `symbol` | query | 아니요 | string |  |
| `limit` | query | 아니요 | integer | default: 100; minimum: 1; maximum: 1000 |

| HTTP | 응답 |
| --- | --- |
| 200 | [OrderListEnvelope](/api-docs/generated/schemas.md#schema-orderlistenvelope) |

### 주문 이력 {#listorderhistory}

`GET https://api.btxpro.co.kr/v1/orders/history`

인증: **서명 + read**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `walletId` | query | 아니요 | integer | minimum: 1; maximum: 255 |
| `symbol` | query | 아니요 | string |  |
| `limit` | query | 아니요 | integer | default: 100; minimum: 1; maximum: 1000 |
| `startTime` | query | 아니요 | integer | minimum: 0; format: "int64" |
| `endTime` | query | 아니요 | integer | minimum: 1; format: "int64" |

| HTTP | 응답 |
| --- | --- |
| 200 | [OrderListEnvelope](/api-docs/generated/schemas.md#schema-orderlistenvelope) |

### 주문 상세 {#getorder}

`GET https://api.btxpro.co.kr/v1/orders/{orderId}`

인증: **서명 + read**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `orderId` | path | 예 | string | pattern: "^[1-9][0-9]*$" |

| HTTP | 응답 |
| --- | --- |
| 200 | [OrderEnvelope](/api-docs/generated/schemas.md#schema-orderenvelope) |

### 주문 취소 {#cancelorder}

`DELETE https://api.btxpro.co.kr/v1/orders/{orderId}`

인증: **서명 + trade**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `orderId` | path | 예 | string | pattern: "^[1-9][0-9]*$" |
| `walletId` | query | 아니요 | integer | minimum: 1; maximum: 255 |
| `symbol` | query | 아니요 | string |  |

| HTTP | 응답 |
| --- | --- |
| 200 | [OrderEnvelope](/api-docs/generated/schemas.md#schema-orderenvelope) |
| 422 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |
| 504 | [ErrorEnvelope](/api-docs/generated/schemas.md#schema-errorenvelope) |

### 체결 이력 {#listfills}

`GET https://api.btxpro.co.kr/v1/fills`

인증: **서명 + read**

| 이름 | 위치 | 필수 | 타입 | 설명과 제약 |
| --- | --- | --- | --- | --- |
| `walletId` | query | 아니요 | integer | minimum: 1; maximum: 255 |
| `symbol` | query | 아니요 | string |  |
| `limit` | query | 아니요 | integer | default: 100; minimum: 1; maximum: 1000 |
| `startTime` | query | 아니요 | integer | minimum: 0; format: "int64" |
| `endTime` | query | 아니요 | integer | minimum: 1; format: "int64" |

| HTTP | 응답 |
| --- | --- |
| 200 | [Envelope](/api-docs/generated/schemas.md#schema-envelope) + object |