# 응답과 공통 규칙

## 주소와 경로

REST는 `https://api.btxpro.co.kr`, WS는 `wss://api-ws.btxpro.co.kr`입니다. 대부분의 REST 경로는 `/v1`으로 시작하며 `/health`, `/ready`만 예외입니다. WS 연결 경로는 `/v1/market/stream`, `/v1/user/stream`입니다.

## REST 응답 {#rest-responses}

일반적인 성공 응답:

```json
{
  "data": {},
  "requestId": "req_1783420800123456789",
  "serverTime": 1783420800123
}
```

오류 응답:

```json
{
  "error": { "code": "INVALID_REQUEST", "message": "Request is invalid." },
  "requestId": "req_1783420800123456789",
  "serverTime": 1783420800123
}
```

`GET /health`는 본문 없는 HTTP 200, WS 업그레이드는 HTTP 101이므로 이 JSON envelope를 사용하지 않습니다. JSON 응답에는 `Cache-Control: no-store`가 설정됩니다.

## 요청 추적

`X-Request-Id`가 응답 헤더와 JSON의 `requestId`에 포함됩니다. 클라이언트가 이 헤더를 지정할 경우 80자 이내의 영문·숫자·`-_.:`로 구성합니다. 장애 문의나 로그 연계에 사용하며, 주문의 중복 처리를 방지하는 값은 아닙니다.

## 숫자와 시각

- 가격·수량·금액·수수료·잔고는 십진수 **문자열**입니다. 부동소수점 변환 대신 decimal 연산을 사용합니다.
- `orderId`와 같은 문자열 ID는 숫자로 변환하지 않고 보존합니다.
- `serverTime`, 주문 조회의 `startTime`·`endTime`은 Unix 밀리초입니다.
- Feed의 `publishedMicrotime`·`creationMicrotime`·`updateMicrotime` 및 WS 체결의 `microtime`은 Unix 마이크로초입니다. 개별 모델의 필드명을 확인하세요.
- 마켓 식별자는 `BTC-USDT`와 같은 `symbol`입니다. 현재 지원 여부와 통화 ID는 마켓 목록에서 확인합니다.

## 쿼리와 목록

쿼리 키는 한 번만 보내고 빈 값을 보내지 마세요. 정확한 기본값·범위는 [전체 엔드포인트](/api-docs/generated/rest.md)에 표시됩니다.

거래 목록의 `limit` 최대값은 1000입니다. 주문·체결 이력은 기본적으로 요청 시점까지 최근 30일을 조회하며 `startTime`, `endTime`으로 범위를 지정할 수 있습니다. `hasMore`가 있는 응답은 추가 데이터가 있을 수 있음을 표시합니다. 거래 이력 API는 Feed의 `cursor` 페이지네이션을 제공하지 않습니다.

Feed 일반 목록은 기본 20개, 최대 100개이며 `hasMore`와 `nextCursor`를 제공합니다. 다음 페이지에는 이전 응답의 `nextCursor`를 `cursor`로 전달합니다. cursor는 정렬 방식에 연결되므로 정렬을 바꾸면 초기화합니다. `q` 검색은 `sort`·`cursor`와 함께 사용할 수 없으며 결과 개수는 limit으로 제한됩니다.

## 권한

| 작업 | 권한 |
| --- | --- |
| 공개 REST·공개 WS | 없음 |
| `GET /v1/account` | 유효한 서명된 키 |
| 지갑·잔고·주문·체결 조회 | read |
| 주문 생성·취소 | trade |
| 개인 WS 연결 | read |
| 개인 WS 주문 명령 | read로 연결한 뒤 trade 추가 확인 |

현재 키의 접근 범위는 계정에서 볼 수 있는 전체 지갑입니다. 외부 API에는 지갑별 키 범위 설정이 없습니다.