> For the complete documentation index, see [llms.txt](https://docs.nexus.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.nexus.xyz/api-reference/ko/guides/known-gaps.md).

# 알려진 제약 사항

API 계약의 공백과 불일치를, 채워 넣지 않고 표시해 둔 목록입니다.

**이 페이지는 계약이 명시하지 않는 사항의 목록입니다.** 레퍼런스 섹션의 엔드포인트 페이지는 `openapi.json`에서 생성되며, 계약이 선언하는 내용만을 그대로 설명합니다. 계약에 언급이 없거나, 모호하거나, 내부적으로 모순되는 부분은 그럴듯한 문장으로 공백을 채우는 대신 이 페이지에 기록합니다.

동작을 직접 읽지 않고 추론해서 사용하는 작업을 기반으로 개발하기 전에 이 페이지를 읽으십시오.

각 항목은 해당하는 API 영역 아래에 있습니다. 여기 있는 어떤 내용도 로드맵상의 약속이 아닙니다. 이는 현재 상태의 계약에 대한 관찰입니다.

**기준선은 사양 `0.9.90`에 대해 검증되었으며, 아래의 모든 항목은 사양이 올라갈 때마다 다시 검사됩니다**. 검사는 `.github/scripts/known_gaps_check.py`가 수행합니다. 각 항목은 `known-gaps-assertions.json`에 계약에 대한 조건식(predicate)을 등록합니다. 조건식이 더 이상 성립하지 않으면 해당 공백이 채워진 것이며, 항목이 제거될 때까지 CI가 실패합니다. 구조가 아니라 문장 내용에 대해 주장하는 항목은 수동 검증으로 표시되며, 마지막으로 대조한 사양 버전을 함께 기록합니다. 같은 게이트는 이 버전도 최신 상태로 유지하도록 요구합니다.

오래된 공백 목록은 공백 목록이 없는 것보다 나쁩니다. `0.9.27`과 `0.9.63` 사이에 이 목록은 최신 상태를 잃었습니다. 여덟 개 항목이 틀렸고, 그중 세 개는 계약이 이미 해결한 공백을 설명하고 있었습니다. 그래서 이제 검사는 다시 읽겠다는 약속이 아니라 기계적으로 이루어집니다.

## 거래

* **배치 한도.** `POST /orders/batch`에는 최대 배치 길이가 선언되어 있지 않으며, 계약은 배치가 요청 한도에 어떤 가중치로 계산되는지(요청 1건인지, 요소마다 1건인지) 명시하지 않습니다.
* **`reduce_only`.** 설명 없이 불리언으로만 선언되어 있습니다. 조건부 및 트레일링 주문 유형과의 상호작용은 명시되어 있지 않습니다.
* **`PreviewResponse` 필드 의미.** 여덟 개 필드에 타입은 있지만 계약에 설명이 없습니다.
* **트리거 방향.** 스탑 및 익절 계열에 대해 "불리한(adverse)" 방향과 "유리한(favorable)" 방향이 `side`별로 공식 정의되어 있지 않습니다.
* **주문 유효 조건 × 조건부 유형.** 계약은 여섯 가지 조건부 주문 유형에 어떤 `time_in_force` 값이 유효한지(예: `StopMarket`에 `PostOnly`) 명시하지 않습니다.
* **수정 가능 여부.** "liquidation orders are not amendable"(청산 주문은 수정할 수 없음)이라는 것 외에, 계약은 조건부 주문이나 트레일링 주문을 수정할 수 있는지, 또는 수정으로 `time_in_force`를 바꿀 수 있는지 명시하지 않습니다.
* **`stop_price` 제거.** 지원 중단(deprecated)으로 표시되어 있지만 제거 버전이나 날짜가 명시되어 있지 않습니다.

## 포지션

* **`leverage`는 현재 항상 `null`입니다.** 계약은 이 값이 "currently always `null`"이며 `leverage_error: "margin_state_not_mirrored"`라고 명시하지만, 값을 채울 목표 시점은 제시하지 않습니다. 클라이언트는 이 엔드포인트에서 포지션별 레버리지를 읽을 수 없습니다.
* **종료된 포지션에 시장별 필터가 없습니다.** `GET /positions/closed`는 `limit`과 `cursor`만 받으므로, 조회 범위를 단일 시장으로 좁힐 방법이 없습니다. `market_id`도 `symbol`도 받지 않습니다. 응답 필드는 `0.9.74`에서 `symbol`로 이름이 바뀌었고, 파라미터는 어느 이름으로도 존재한 적이 없습니다.
* **보존 기간이 명시되지 않았습니다.** `funding_paid`는 "bounded by the funding history the indexer retains"(인덱서가 보존하는 펀딩 이력으로 제한됨)로 문서화되어 있지만 보존 기간은 제시되지 않습니다. 이 엔드포인트의 커서 페이지네이션은 더 이상 이 공백에 포함되지 않습니다. `GET /positions/closed`는 `limit`에 200건의 보존 구간을 문서화하고 있습니다.
* **종료된 포지션에 `429`가 없습니다.** `GET /positions/closed`와 그 `/api/v1` 쌍둥이 경로는 `200`과 `401`만 선언합니다. 같은 요청 한도 계층이 적용되는데도, 계약은 다른 포지션 작업이 선언하는 `429` 응답을 누락하고 있습니다.
* **교차 마진 전용.** `initialMargin`은 "under the engine's cross-margin model"(엔진의 교차 마진 모델 기준)로 정의되어 있으며, 계약은 인덱서가 격리/사용자 지정 증거금 배분을 미러링하지 않는다고 적고 있습니다. 따라서 격리 마진 포지션의 실제 배분은 이곳에서 읽을 수 없습니다.
* **미결제 포지션 수나 합계가 없습니다.** `GET /positions`의 응답은 엔벨로프도 페이지네이션도 없는 배열뿐이므로, 한 응답에 담길 수 있는 포지션 수의 상한이 문서화되어 있지 않습니다.

## 계정

* **`direction`이 열거되어 있지 않습니다.** `POST /account/margin`은 요청 스키마를 전혀 선언하지 않습니다. 예시에는 `"direction": "add"`가 나오고 요약과 `400` 설명은 제거도 지원된다고 암시하지만, 계약은 제거에 쓰이는 값을 명시하지 않습니다. 필드 타입을 밝히거나 필수 필드를 표시하지도 않습니다.
* **두 작업이 요청 스키마를 선언하지 않습니다.** `POST /account/deposit`과 `POST /account/margin`에는 요청 예시만 있으므로, 계약으로 생성한 클라이언트는 두 작업 모두에서 타입이 없는 요청 본문을 받게 됩니다. 응답에는 타입이 있으며(`DepositResponse`, `AdjustMarginResponse`), 선언되지 않은 것은 요청 쪽입니다.
* **겹치는 두 가지 입금 경로.** `POST /account/deposit`과 `POST /deposits`는 둘 다 담보를 입금하고 둘 다 `DepositResponse`를 반환하지만, 계약은 어느 쪽을 써야 하는지, 운영상 어떻게 다른지 명시하지 않습니다. 응답이 같으므로 반환된 형태로는 둘을 구분할 수 없습니다.
* **상태 어휘가 서로 다릅니다.** `Withdrawal.status`는 `pending` / `settled` / `failed`이고, `FundsEntry.status`는 `pending` / `submitted` / `confirmed` / `failed`입니다. 같은 수명 주기에 두 가지 이름 체계와 서로 다른 단계 수가 있어, 둘 사이에 완전한 대응 관계가 없습니다. `submitted`에는 `Withdrawal` 쪽 대응 값이 없고, `settled`에는 `FundsEntry` 쪽 대응 값이 없습니다.
* **요청 한도 등급의 대소문자 표기가 일관되지 않습니다.** `RateLimitStatus.tier`는 소문자(`pro`, `marketmaker`, `unlimited`)로 문서화되어 있습니다. `429` 본문 예시는 `"tier": "Pro"`를 반환합니다. 관리자용 등급 관리 작업은 `MarketMaker`와 `Pro`를 사용합니다. 계약은 표준 대소문자 표기를 명시하지 않습니다.
* **`429` 적용 범위가 고르지 않습니다.** 같은 요청 한도 계층의 적용을 받는 여러 작업이 `200`과 `401`만 선언합니다. 총자산 이력 작업 두 개, 주문 내역 작업 두 개, 연결 해제 시 취소 GET 및 PUT 모두, `GET /withdrawals`, `GET /deposits`, `POST /deposits`, `GET /orders/{order_id}`, 요청 한도 상태 작업 두 개가 이에 해당합니다.
* **보존 구간은 기간이 아니라 레코드 수입니다.** 이제 각 작업은 보존 구간의 크기(체결 1,000건, 주문 내역 500건, 종료된 포지션 200건, 총자산 포인트 720개, 거래 10,000건)를 명시합니다. 그러나 어떤 작업도 그것이 시간상 얼마나 거슬러 올라가는지는 밝히지 않으므로, 클라이언트는 조회가 일주일을 다루는지 1년을 다루는지 알 수 없습니다. `volume_30d` 과소 집계는 더 이상 이 공백에 포함되지 않습니다. `volume_30d_estimated`가 어떤 보장이 적용되는지 명시합니다.
* **두 곳에서 `limit` 최댓값이 설명보다 낮습니다.** `GET /withdrawals`와 `GET /deposits`는 모두 `limit`의 상한이 100이고 기본값도 100이므로, 이 파라미터로는 페이지를 줄이는 것만 가능합니다. 두 작업 모두 `cursor`를 받지 않으므로 100건을 넘어 페이지를 넘길 방법이 없습니다.
* **`EquityPoint.equity`는 JSON 숫자입니다.** 이 태그의 다른 모든 금전 필드는 손실 없는 10진수 문자열입니다. 계약 자체가 `PortfolioPoint.equity`와의 불일치를 언급하고 클라이언트에게 10진수 값으로 비교하라고 안내하지만, 전송 형식은 여전히 부동소수점 표현입니다.
* **`early_access_allowed`는 참/거짓이 아니라 존재/부재로 표현됩니다.** 계약은 이 필드가 "only when the early-access gate is active"(얼리 액세스 게이트가 활성화된 경우에만) 나타난다고 할 뿐, 무엇이 게이트를 좌우하는지, 필드가 없으면 호출자에게 무슨 의미인지는 명시하지 않습니다.
* **계정별 등급이나 할인 프로그램이 없습니다.** `AccountFees.tier`는 항상 `base`이고, `discounts`는 항상 비어 있으며, `FeeDiscount`에는 정의된 속성이 없습니다. 현재 보존 중인 체결 버퍼에 있는 시장의 시장별 실효 수수료율은 `markets`로 제공됩니다. 어떤 시장이 없다고 해서 전체 기간의 거래에 대해 알 수 있는 것은 아닙니다. 호출자는 여전히 `schedule`을 새 값이 추가될 수 있는 문자열로 다루고 `per_market`, `reference`, 값이 0인 `unknown` 센티널을 구분해야 합니다.
* **포지션을 포함하는 모든 응답(`AccountSummary`, `AccountState`)에서 `Position.leverage`는 현재 항상 `null`이며**, `leverage_error: "margin_state_not_mirrored"`가 함께 옵니다. [`GET /positions`](https://docs.nexus.xyz/api-reference/positions/fetch-positions)(영어)를 참조하십시오.

## 관리자

* **등급 이름이 열거되어 있지 않습니다.** 스키마도, `enum`도, 목록도 없습니다. 여기서는 예시로 `MarketMaker`만 나오며, `pro` / `marketmaker` / `unlimited`는 `RateLimitStatus` 설명의 문장 속에만 나옵니다. 운영자는 계약에서 유효한 값의 집합을 알 수 없습니다.
* **계약 전반에서 대소문자 표기가 일관되지 않습니다.** 이 작업들은 `MarketMaker`와 `Pro`를 사용합니다. `RateLimitStatus.tier`는 소문자(`pro`, `marketmaker`, `unlimited`)로 문서화되어 있습니다. 공유 `429` 본문 예시는 `"tier": "Pro"`를 반환합니다. 계약은 어떤 표기가 표준인지, 비교가 대소문자를 구분하는지 명시하지 않습니다.
* **요청 스키마가 없고, 응답 스키마가 없는 작업도 하나 있습니다.** 세 작업 모두 요청 스키마를 선언하지 않으므로, 계약으로 생성한 클라이언트는 모든 요청 본문을 타입 없이 받게 됩니다. `GET`과 `PUT /admin/tiers`는 `200` 응답 스키마를 선언하지만, `DELETE /admin/tiers/{address}`는 선언하지 않습니다.
* **삭제에는 `404 Address not in allowlist`가 있지만, 다른 곳에는 허용 목록이 없습니다.** `DELETE /admin/tiers/{address}`는 주소가 "not in allowlist"일 때 `404`를 반환하지만, `PUT /admin/tiers`는 허용 목록 전제 조건을 문서화하지 않으며 `GET /admin/tiers`는 결과를 "overrides"로 설명합니다. 재정의 저장소와 허용 목록의 관계는 명시되어 있지 않습니다.
* **`401`도, 요청 한도도 선언되어 있지 않습니다.** 이 작업들은 `200`, `403`, (삭제의 경우) `404`만 선언합니다. 잘못된 시크릿과 구분되는 형식이 잘못된 `Authorization` 헤더에 대한 동작이 문서화되어 있지 않고 요청 한도 응답도 없으므로, Bearer 시크릿에는 선언된 제한이 없습니다.
* **감사 추적이 노출되지 않습니다.** 계약의 어떤 부분도 누가 언제 등급을 설정했는지 노출하지 않습니다. `GET /admin/tiers`는 현재 상태만 반환합니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.nexus.xyz/api-reference/ko/guides/known-gaps.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.