> 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/readme.md).

# API 레퍼런스

Nexus Exchange의 프로그래밍 인터페이스로, 모든 엔드포인트와 이를 설명하는 가이드, 공식 클라이언트를 다룹니다.

트레이더가 Nexus Exchange에서 할 수 있는 모든 작업은 프로그래밍 방식으로도 이용할 수 있습니다. 이 섹션에는 엔드포인트별 페이지, 이를 설명하는 직접 작성한 가이드, 공식 지원 클라이언트가 있습니다.

|            |                                                                                                                                                                                                      |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **여기서 시작** | [시작하기](/api-reference/ko/guides/get-started.md) · [인증](/api-reference/ko/guides/authentication.md) · [에이전트 키](/api-reference/ko/guides/agent-keys.md)                                                |
| **구축 전에**  | [주문 유형](/api-reference/ko/guides/order-types.md) · [요청 한도](/api-reference/ko/guides/rate-limits.md) · [오류](/api-reference/ko/guides/errors.md) · [알려진 제약 사항](/api-reference/ko/guides/known-gaps.md) |
| **레퍼런스**   | 엔드포인트마다 한 페이지씩, 사이드바에서 영역별로 묶여 있습니다                                                                                                                                                                  |
| **스키마**    | [스키마 레퍼런스](https://docs.nexus.xyz/api-reference/guides/schemas)(영어)                                                                                                                                  |

## 기본 URL

계약(contract)은 문서 수준에서 세 개의 서버를 다음 순서로 선언합니다.

| 서버            | URL                                | 용도                                                                                                                                   |
| ------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| 퍼블릭 테스트넷(기본값) | `https://api.testnet.nexus.xyz/v1` | 테스트용 자금. **접두사 없는** 경로를 위한 `/v1` 전송 기본 경로입니다. 목록의 첫 번째이므로 생성기가 기본값으로 고르는 기본 경로입니다.                                                   |
| 메인넷           | `https://api.nexus.xyz/v1`         | **실제 자금.** "첫 번째 `https` 서버"를 찾는 어떤 도구도 실제 자금 대상에 닿지 않도록 의도적으로 테스트넷 다음에 나열했습니다. 아직 해석(resolve)되지 않습니다. DNS는 별도의 인프라 변경입니다(ENG-8155). |
| 로컬 개발         | `http://localhost:9090`            | 사용자의 로컬 머신에서 실행되는 인덱서.                                                                                                               |

계약은 기본 네트워크를 지정하지 않으므로 네트워크를 명시적으로 선택하십시오. 위 표의 "기본값"은 테스트넷이 `servers[0]`, 즉 사용자가 선택하지 않을 때 생성기가 고르는 기본 경로라는 뜻일 뿐입니다. 레거시 게이트웨이 기본 경로 `https://exchange.nexus.xyz/api/exchange`는 **폐기되었습니다**. 계약에서 제거되었으며, 대체 경로를 알려 주는 JSON 본문과 함께 HTTP 410으로 응답합니다. SDK, CLI, MCP 서버는 요청 한도와 등급을 적용하는 위의 퍼블릭 테스트넷 기본 경로를 가리키도록 설정하십시오.

### 버전 지정(`/api/v1`) 경로와 접두사 없는 경로

110개 경로 중 40개는 접두사 없는 경로의 `/api/v1/…` 버전 지정 형제 경로입니다. 이들은 같은 작업이며, 버전 지정 마운트를 통해 접근합니다. 두 형식 모두 퍼블릭 테스트넷 호스트에서 작동합니다.

```
https://api.testnet.nexus.xyz/v1/tickers       → 200
https://api.testnet.nexus.xyz/api/v1/tickers   → 200
```

**`/v1` 기본 경로에서는 접두사 없는 형식을 우선 사용하십시오.** 문서 수준의 `servers` 항목이 선언하는 형식이며, 공식 클라이언트가 옮겨 가고 있는 구성입니다. 계약은 어느 쪽도 `deprecated`로 표시하지 않습니다. 다섯 개의 `/api/v1/bridge/…` 경로는 아직 계약에 접두사 없는 표기가 없으므로, 당분간 `/api/v1` 형식으로 호출하십시오.

**URL 경로가 아니라 계약 경로에 서명하십시오.** 마운트를 선택하는 전송 접두사(퍼블릭 테스트넷 기본 경로의 `/v1`)는 요청이 서명을 검증하는 서비스에 도달하기 전에 제거되므로, HMAC 정규 문자열에 포함되지 않습니다. `/api/v1` 접두사는 계약 경로의 일부이므로 서명에 *포함됩니다*. `https://api.testnet.nexus.xyz/api/v1/tickers`를 호출하면 `/api/v1/tickers`에 서명하고, `https://api.testnet.nexus.xyz/v1/tickers`를 호출하면 `/tickers`에 서명합니다. [인증](/api-reference/ko/guides/authentication.md)을 참조하십시오.

{% hint style="info" %}
**`/api/v1` 경로에는 `servers` 재정의가 있으며, 클라이언트는 이를 따라야 합니다.** 40개 경로 모두 퍼블릭 테스트넷 **호스트 루트** `https://api.testnet.nexus.xyz`, 또는 로컬 개발용 `http://localhost:9090`을 가리키는 경로 수준 재정의를 선언합니다. 전체 작업 경로가 여기에 덧붙으므로 `/api/v1/tickers`는 `https://api.testnet.nexus.xyz/api/v1/tickers`로 해석됩니다. 이것이 생성된 레퍼런스 페이지가 보여 주는 "선언된 서버(Declared server)"이며, 이를 따르는 생성 클라이언트는 API에 도달합니다.

이 재정의가 있는 이유는 해당 기본 경로가 문서 수준의 기본 경로와 다르기 때문입니다. 문서의 테스트넷 항목은 `/v1`을 포함하며 접두사 없는 경로(`https://api.testnet.nexus.xyz/v1/tickers`)를 기대하지만, 접두사가 있는 경로에는 호스트 루트가 필요합니다. 두 부분을 직접 조합하면 `https://api.testnet.nexus.xyz/v1/api/v1/…`이 되며, 이는 계약이 이 경로들에 대해 선언하는 URL이 아닙니다. 계약에 따르면 퍼블릭 테스트넷 차트도 이 URL을 받아들입니다. 차트는 바깥쪽 `/v1`만 제거하고, 요청은 여전히 `/api/v1/…`에 서명합니다.
{% endhint %}

### 이 섹션을 읽는 방법

**레퍼런스 페이지는 계약에서 생성됩니다.** 각 페이지는 해당 작업에 대해 `openapi.json`이 선언하는 내용만 기술합니다: 파라미터, 요청 본문, 응답, 인증 방식, 요청 한도 등급. CI가 페이지를 다시 렌더링하고 비교하므로 계약과 어긋날 수 없습니다.

**가이드는 사람이 직접 작성합니다.** 엔드포인트별 페이지가 다룰 수 없는 내용을 다룹니다: 주문을 넣는 모든 작업에 걸친 주문 유형별 요구 사항 표, 부호 규칙, 오류 모델, 그리고 계약이 명시하지 않는 사항 목록.

**이 섹션은 엔드포인트나 스키마가 몇 개인지 명시하지 않습니다.** 지난번에는 직접 관리하던 개수가 어긋났습니다. 이 섹션의 이전 버전은 마이너 릴리스 18개만큼 뒤처진 사양 버전을 게시했고, 작업 및 스키마 개수도 마찬가지로 뒤처져 있었습니다. 사이드바는 계약에서 생성되며, 계약은 `/openapi.json`에서 제공됩니다. 둘 다 권위 있는 출처이므로, 어느 쪽도 본문에서 숫자를 다시 언급할 필요가 없습니다.

### OpenAPI 사양

이 API는 계약 우선(contract-first)입니다. 모든 경로, 요청/응답 본문, CCXT 메서드 매핑을 담은 기계 판독용 스키마는 [`nexus-xyz/nexus-exchange-api`](https://github.com/nexus-xyz/nexus-exchange-api)에 게시되고 `/openapi.json`에서 실시간으로 제공됩니다. 릴리스는 [GitHub Releases](https://github.com/nexus-xyz/nexus-exchange-api/releases)에서 추적됩니다. 아래의 SDK, CLI, MCP 서버는 각각 이 사양의 릴리스 버전에서 생성되거나 그 버전에 고정되므로 게이트웨이와 일치합니다.

### SDK

| 언어         | 저장소                                                                   | 용도                        |
| ---------- | --------------------------------------------------------------------- | ------------------------- |
| Rust       | [`nexus-exchange-rs`](https://github.com/nexus-xyz/nexus-exchange-rs) | 지연 시간에 민감한 클라이언트와 시장 조성 봇 |
| TypeScript | [`nexus-exchange-ts`](https://github.com/nexus-xyz/nexus-exchange-ts) | 웹, Node, 엣지 애플리케이션        |
| Python     | [`nexus-exchange-py`](https://github.com/nexus-xyz/nexus-exchange-py) | 리서치, 백테스팅, 스크립팅           |

각 SDK는 요청 서명(HMAC 또는 에이전트 키), 페이지네이션, WebSocket 구독 수명 주기를 처리하므로 직접 다시 구현할 필요가 없습니다. SDK별 서명 비용과 사용자의 등급을 따라갈 수 있는지는 [SDK별 서명 비용](/api-reference/ko/guides/rate-limits.md#can-your-signer-keep-up)을 참조하십시오. 버전 지원과 호환성이 깨지는 변경(breaking change) 정책은 각 저장소의 README에 문서화되어 있습니다.

[포트폴리오 및 계정 상태](/api-reference/ko/guides/portfolio.md)는 네 가지 인터페이스 모두의 계정 및 포트폴리오 엔드포인트를 함께 다룹니다: 통합 계정 상태, 출금 가능 잔액, 수수료 체계, 보강된 포지션 리스크 필드, 총자산/손익/거래량 시계열.

무엇으로 구축하든 같은 예산이 적용됩니다. 요청은 개수가 아니라 **초당 가중치**로 차감되며, 읽기, 주문 쓰기, WebSocket 제어 평면은 서로 독립된 세 개의 풀을 사용합니다. 클라이언트 측 리미터를 작성하기 전에 [요청 한도](/api-reference/ko/guides/rate-limits.md)를 읽으십시오. 요청 개수로 속도를 조절하는 클라이언트는 자체 카운터가 아직 정상으로 보이는 동안에도 거부됩니다.

### 명령줄

[`nexus-exchange-cli`](https://github.com/nexus-xyz/nexus-exchange-cli)는 대화형 사용과 셸 스크립팅을 위해 같은 API를 감쌉니다. 코드를 작성하지 않고도 키를 관리하고, 주문을 넣고 취소하며, 계정 상태를 조회할 수 있습니다. `nexus --version`은 CLI가 기반으로 하는 API 사양 및 SDK 버전을 보고합니다.

### MCP 서버

[`nexus-exchange-mcp`](https://github.com/nexus-xyz/nexus-exchange-mcp) 서버는 거래소를 [Model Context Protocol](https://modelcontextprotocol.io) 도구로 노출하므로, AI 어시스턴트나 에이전트가 사람이 쓰는 클라이언트와 같은 인증된 API를 통해 거래하고 계정 상태를 읽을 수 있습니다. [`@nexus-xyz/exchange-mcp`](https://www.npmjs.com/package/@nexus-xyz/exchange-mcp)로 게시되어 있습니다.

```bash
claude mcp add nexus-exchange -- npx -y @nexus-xyz/exchange-mcp
```

stdio로 실행되므로 자격 증명은 서버를 추가한 머신에 그대로 남으며, 공개 시장 데이터 도구는 키 없이도 작동합니다.

### 네트워크 선택

거래소는 현재 개발 프리뷰로 **Nexus Testnet**에서 운영되며, 퍼블릭 **메인넷**이 뒤이어 출시될 예정입니다. 모든 인터페이스는 한 번에 하나의 네트워크(`testnet`, `mainnet` 또는 `local`)를 대상으로 하며, 클라이언트를 생성할 때 선택합니다. 클라이언트는 해당 네트워크의 REST 및 WebSocket 대상, 포셋 제공 여부, 서명 도메인을 함께 묶습니다. SDK, CLI, MCP 서버는 네트워크를 전달하지 않으면 테스트넷을 사용하며, 메인넷은 아직 접근할 수 없습니다. 자격 증명은 생성된 네트워크로 범위가 한정됩니다.

각 인터페이스가 네트워크를 선택하는 방법, 대상을 재정의하는 방법, API 키를 네트워크에 묶는 요소는 [네트워크](/api-reference/ko/guides/networks.md)를, 현재 기본 URL은 [API 및 요청 한도](https://docs.nexus.xyz/exchange/apis-and-rates)를, 전체 연결 흐름은 [빠른 시작](https://docs.nexus.xyz/exchange/trading/quickstart)을 참조하십시오.

### 인증

인증 방식은 모든 인터페이스에서 동일합니다. 지갑으로 고정된 메시지에 서명(EIP-191)하여 수명이 짧은 세션 토큰을 얻고, 그 토큰을 한 번 사용해 HMAC API 키를 발급한 뒤, 각 거래 요청에 그 키로 서명합니다. SDK와 CLI는 요청에 자동으로 서명합니다. 실행 가능한 예시가 포함된 전체 안내는 [빠른 시작](https://docs.nexus.xyz/exchange/trading/quickstart)에 있습니다.

> **상태:** 테스트넷의 개발 프리뷰. 인터페이스는 OpenAPI 사양을 릴리스 단위로 따라갑니다. 프로덕션에서는 사양 버전을 고정하고, 업그레이드 전에 각 저장소의 릴리스 노트를 확인하십시오. 테스트넷 자격 증명과 잔액에는 실제 가치가 없습니다.


---

# 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/readme.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.