> For the complete documentation index, see [llms.txt](https://docs.aftermath.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.aftermath.finance/ko/perpetuals/architecture/market-makers.md).

# 마켓 메이커

Aftermath Perpetuals 마켓 메이커 통합 가이드 — 리쿼트 루프, 와이어 포맷, 실시간 데이터, 리스크 컨트롤.

지정 마켓 메이커 프로그램은 없으며, 누구에게도 지연 시간 우대가 주어지지 않습니다. 누구나 Aftermath Perpetuals에서 마켓 메이킹을 할 수 있습니다.

기술 통합 관련 문의는 [Discord](https://discord.gg/VFqMUqKHF3)에 참여하거나 [X](https://x.com/AftermathFi)로 메시지를 보내 주십시오.

## API 기본 정보

| 리소스        | URL                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------- |
| API 프리픽스   | `https://aftermath.finance/api/...`                                                                  |
| Swagger UI | [`https://aftermath.finance/docs`](https://aftermath.finance/docs)                                   |
| OpenAPI 스펙 | [`https://aftermath.finance/api/openapi/spec.json`](https://aftermath.finance/api/openapi/spec.json) |
| 에이전트 스킬    | [`github.com/AftermathFinance/skills`](https://github.com/AftermathFinance/skills)                   |

필드 이름과 타입의 공식 기준은 OpenAPI 스펙입니다. 요청 본문을 손으로 작성하지 말고 스펙에서 타입을 생성하십시오.

{% hint style="info" %}
에이전트 스킬 저장소는 이 통합 패턴들을 코딩 에이전트용으로 패키징한 것입니다. Claude Code, Codex, Cursor로 개발한다면 요청 본문을 작성하기 전에 에이전트가 이 저장소를 참조하게 하십시오.
{% endhint %}

## 권장 통합 방식

CCXT 레이어보다는 네이티브 Perpetuals REST 엔드포인트(`/api/perpetuals/account/transactions/*`) 사용을 권장합니다. 네이티브 엔드포인트는 가스 관리를 완전히 제어할 수 있고, 프로그래머블 트랜잭션 블록(PTB) 같은 Sui 네이티브 기능도 활용할 수 있습니다.

모든 네이티브 엔드포인트는 base64로 인코딩된 `TransactionKind`를 담은 `TxKindResponse`를 반환합니다. 이를 디코딩해 완전한 `Transaction`으로 감싸고, 지갑으로 서명한 뒤 Sui 클라이언트로 제출합니다.

### 주요 엔드포인트

**주문 취소 및 등록** (`POST /api/perpetuals/account/transactions/cancel-and-place-orders`)

마켓 메이커의 핵심 엔드포인트입니다. 기존 주문 취소와 신규 주문 등록을 단일 PTB에서 원자적으로 처리하므로, 취소와 등록을 별도 트랜잭션으로 보내는 것보다 가스가 적게 듭니다. 두 작업 사이에 중간 상태가 없어 리쿼트 도중 오더북 뎁스가 완전히 비는 일이 없습니다. 호가 갱신이나 주문 그리드 관리에 사용하십시오.

**지정가 주문 등록** (`POST /api/perpetuals/account/transactions/place-limit-order`)

개별 주문 등록용입니다. 같은 트랜잭션에서 손절매(SL)/이익 실현(TP)을 인라인으로 첨부할 수 있습니다.

**시장가 주문 등록** (`POST /api/perpetuals/account/transactions/place-market-order`)

시장 가격 즉시 체결용입니다. 인라인 SL/TP도 지원합니다.

**스케일 주문 등록** (`POST /api/perpetuals/account/transactions/place-scale-order`)

단일 트랜잭션으로 수량을 가격 구간에 분산 배치합니다. DCA 방식 진입, 유동성 래더 구성, 여러 가격대에 리스크를 분산할 때 사용하십시오.

**TWAP 주문** (`POST /api/perpetuals/account/transactions/create-twap-orders`, `edit-twap-orders`, `cancel-twap-orders`)

일정 수량의 체결을 시간에 걸쳐 예약합니다. 예약 수량과 처리된 수량은 `POST /api/perpetuals/account/twap-order-datas`로 조회합니다. 누적된 재고를 스프레드를 한꺼번에 지불하지 않고 정리할 때 사용하십시오.

{% hint style="info" %}
위의 모든 계정 트랜잭션 라우트에는 `/api/perpetuals/vault/transactions/*` 아래에 동일한 볼트용 라우트가 있으며, `cancel-and-place-orders`도 포함됩니다. 개인 계정이 아닌 볼트에서 호가를 낸다면 요청 형식은 동일합니다. `accountId`를 `vaultId`로 바꾸기만 하면 됩니다.
{% endhint %}

## 리쿼트 루프

`cancel-and-place-orders`는 하루에 수천 번 호출하게 되므로 모든 필드를 익혀 두십시오.

| 필드                               | 설명                                                                                                                                              |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `accountId`                      | 숫자 계정 ID이며 BigInt 문자열(`"123n"`)로 전송합니다. 볼트에서 호가를 낼 때는 대신 `vaultId`를 사용합니다.                                                                      |
| `accountCapId`                   | 트랜잭션을 승인하는 계정 캐퍼빌리티의 객체 ID(선택 사항).                                                                                                              |
| `walletAddress`                  | 필수. 환불되는 가스 코인을 수령합니다.                                                                                                                          |
| `marketId`                       | 필수. 호가를 낼 클리어링 하우스입니다.                                                                                                                          |
| `orderIdsToCancel`               | 체인이 부여한 주문 ID(BigInt 문자열). 생략하면 아무것도 취소하지 않습니다.                                                                                                 |
| `clientOrderIdsToCancel`         | 체인 ID 대신 **자신이 지정한** ID로 취소합니다. `orderIdsToCancel`과 함께 사용할 수 있습니다.                                                                              |
| `shouldAbortOnMissingId`         | 기본값은 `false`입니다. 아래 설명 참조 — 대부분의 경우 이 기본값이 맞습니다.                                                                                                |
| `ordersToPlace`                  | `{ side, price, size, clientOrderId? }` 배열. 생략하면 아무것도 등록하지 않습니다.                                                                                |
| `orderType`                      | 배치 전체에 적용되는 체결 유형. 아래 표 참조.                                                                                                                     |
| `reduceOnly`                     | `true`이면 등록된 주문이 포지션 크기를 절대 늘리지 않습니다.                                                                                                           |
| `hasPosition`                    | 필수. 계정이 현재 이 마켓에 포지션을 보유하고 있는지 여부.                                                                                                              |
| `expiryTimestamp`                | 등록 주문의 만료 시각(밀리초 epoch, 선택 사항).                                                                                                                 |
| `leverage`                       | 등록 주문에 적용할 레버리지 오버라이드(선택 사항).                                                                                                                   |
| `shouldDeallocateFreeCollateral` | `true`이면 포지션을 뒷받침하지 않는 증거금을 같은 트랜잭션에서 지갑으로 회수합니다.                                                                                               |
| `sponsor`                        | GasPool 스폰서십용 `{ walletAddress, bytes, signature, gasBudget? }`. `bytes`는 `Aftermath Terms and Conditions`의 base64이며, `gasBudget`의 단위는 MIST입니다. |
| `builderCode`                    | `{ integratorId, integratorFee }` — 통합 파트너(인테그레이터)로서 주문 흐름을 라우팅할 때만 해당됩니다.                                                                      |
| `txKind`                         | 확장할 기존 base64 `TransactionKind`. 리쿼트를 직접 구성한 더 큰 PTB에 합성할 수 있습니다.                                                                               |

### 주문 유형

`orderType`은 `ordersToPlace`의 모든 주문에 적용됩니다:

| 값   | 유형        | 동작                                              |
| --- | --------- | ----------------------------------------------- |
| `0` | GTC       | 체결되거나 취소될 때까지 오더북에 남습니다.                        |
| `1` | FOK       | 한 번의 매칭에서 전량 체결되어야 하며, 그렇지 않으면 주문 전체가 취소됩니다.    |
| `2` | Post-Only | 즉시 매칭되지 않는 경우에만 오더북에 추가됩니다. 유동성을 소진하게 되면 거부됩니다. |
| `3` | IOC       | 즉시 체결 가능한 만큼 체결하고 잔량은 취소합니다.                    |

마켓 메이커는 `2`로 호가를 내야 합니다. 호가가 교차 체결되는 일이 없고 테이커 수수료도 절대 내지 않습니다.

### 클라이언트 주문 ID

등록하는 모든 주문에는 선택 사항인 `clientOrderId`를 붙일 수 있습니다. 직접 정하는 `u64` 값으로, BigInt 문자열로 전송합니다. 자신의 ID로 호가를 태그해 두면 체인이 부여한 ID를 다시 읽어 오지 않고도 `clientOrderIdsToCancel`로 취소할 수 있습니다.

이렇게 하면 리쿼트 루프에서 왕복이 한 번 줄어듭니다. 등록 → 주문 ID 조회 → 체인 ID로 취소 → 재등록 대신, 전략이 이미 알고 있는 ID로 계속 호가를 냅니다. 클라이언트 주문 ID는 포지션 상태의 `pendingOrders`와 주문 스트림에도 함께 반환되므로, 체결 내역을 자체 장부와 직접 대사할 수 있습니다.

`clientOrderId`는 `place-limit-order`에서 지원되며, `place-scale-order`에서는 `clientOrderIds`라는 이름으로 지원됩니다.

### 누락된 ID는 기본적으로 오류가 아닙니다

취소하려는 주문이 결정 시점과 트랜잭션 반영 시점 사이에 체결되거나 만료될 수 있습니다. `shouldAbortOnMissingId: false`(기본값)이면 트랜잭션은 누락된 ID를 허용합니다. 나머지 취소와 새 주문은 모두 그대로 처리됩니다.

부분 적용된 리쿼트가 리쿼트를 아예 하지 않는 것보다 나쁜 경우에만 `true`로 설정하십시오. 대부분의 호가 전략에는 해당되지 않습니다. 중단된 트랜잭션은 낡은 호가를 오더북에 그대로 남기며, 이는 해결하려던 바로 그 상황입니다.

### 요청 예시

```json
POST /api/perpetuals/account/transactions/cancel-and-place-orders

{
  "accountId": "123n",
  "accountCapId": "0x...",
  "walletAddress": "0x...",
  "marketId": "0x...",
  "clientOrderIdsToCancel": ["1001n", "1002n", "1003n"],
  "ordersToPlace": [
    { "side": 0, "price": "7250000000000n", "size": "100000000n", "clientOrderId": "1004n" },
    { "side": 0, "price": "7249000000000n", "size": "100000000n", "clientOrderId": "1005n" },
    { "side": 1, "price": "7260000000000n", "size": "100000000n", "clientOrderId": "1006n" },
    { "side": 1, "price": "7261000000000n", "size": "100000000n", "clientOrderId": "1007n" },
    { "side": 1, "price": "7262000000000n", "size": "100000000n", "clientOrderId": "1008n" }
  ],
  "orderType": 2,
  "reduceOnly": false,
  "hasPosition": true,
  "shouldAbortOnMissingId": false
}
```

`side`는 매수 호가(bid)가 `0`, 매도 호가(ask)가 `1`입니다.

## 와이어 포맷 규칙

처음 통합할 때 실패하는 원인 대부분은 이 네 가지 규칙에서 나옵니다.

**BigInt 필드에는 끝에 `n`이 필요합니다.** 네이티브 BigInt 필드는 `n` 접미사가 붙은 JSON 문자열입니다(예: `"123n"`). 일반 `123`과 `"123"`은 모두 실패합니다. 응답도 같은 형식으로 돌아옵니다. 모든 숫자가 BigInt는 아닙니다. 일반 카운터와 밀리초 타임스탬프는 일반 JSON 숫자이므로, 전역으로 변환하지 말고 각 엔드포인트의 스키마를 따르십시오.

**`accountId`는 숫자이며 객체 ID가 아닙니다.** 네이티브 엔드포인트는 숫자 계정 ID를 받습니다. CCXT 쓰기 엔드포인트는 같은 이름으로 계정 캐퍼빌리티 객체 ID(`0x...`)를 받고, CCXT 읽기 엔드포인트는 `accountNumber`를 사용합니다. 숫자 `accountId` 자리에 `0x...` 캐퍼빌리티 ID를 넣는 것이 가장 흔한 통합 실패 원인입니다.

**미리보기 응답은 성공-오류 유니언입니다.** `/api/perpetuals/account/previews/*`는 HTTP `200`과 함께 본문 `{ "error": "..." }`와 헤더 `X-Error-Message: true`를 반환할 수 있습니다. 성공 필드를 읽기 전에 오류 형태인지 먼저 확인하십시오. `200`만으로는 미리보기가 성공했다고 볼 수 없습니다.

**응답은 결정적으로 정렬됩니다.** 마켓은 심볼순, 포지션은 마켓 ID순, 대기 중인 매수·매도 호가는 각각 주문 ID순으로 정렬됩니다. 폴링할 때마다 맵을 다시 만들 필요 없이, 연속된 계정 스냅샷을 위치 기반으로 비교할 수 있습니다.

## 실시간 마켓 데이터

모든 실시간 스트림(오더북, 오라클, 마켓 상태, 계정 업데이트, 캔들)은 단일 WebSocket으로 멀티플렉싱됩니다.

`wss://aftermath.finance/api/perpetuals/ws/updates`

`open` 이후 JSON 프레임을 보내 스트림별로 구독합니다:

```json
{
  "action": "subscribe",
  "subscriptionType": {
    "topOfOrderbook": {
      "marketId": "0x...",
      "priceBucketSize": 0.0001,
      "bucketsNumber": 10
    }
  }
}
```

호가 봇에 보통 필요한 스트림:

| 구독/헬퍼                            | 용도                                                           |
| -------------------------------- | ------------------------------------------------------------ |
| `topOfOrderbook`                 | 버킷 단위 상위 N개 스냅샷. 각 프레임이 완전한 스냅샷이므로 REST 시드도, 델타 관리도 필요 없습니다. |
| `orderbook`                      | 버킷 단위 상단 호가로 부족할 때 사용하는 전체 뎁스 델타.                            |
| `oracle`                         | 해당 마켓의 오라클 가격 업데이트.                                          |
| `subscribeUserOrders`            | `clientOrderId`를 포함한 계정 주문 업데이트용 SDK 헬퍼.                     |
| `subscribeUserCollateralChanges` | 계정 담보 변동용 SDK 헬퍼.                                            |
| `marketCandles`                  | `1m` … `1mo` 구간의 OHLCV 업데이트.                                 |

전체 프레임 스키마, 오류 프레임, 클라이언트 예시는 [WebSockets](https://github.com/clawd-aftermath/aftermath-docs-translations/tree/ko/for-developers/api/websockets.md) 페이지에 있습니다.

{% hint style="warning" %}
**재연결 시 재개 전에 다시 동기화하십시오.** 스냅샷을 다시 가져와 로컬 상태를 원자적으로 교체한 뒤 델타 적용을 재개하십시오. 연결이 끊기기 전의 메모리 상태에서 그대로 이어 가면 안 됩니다.
{% endhint %}

서버 전송 이벤트(SSE)를 선호한다면 `/api/ccxt/stream/*` 아래의 SSE 스트림을 사용할 수 있습니다.

## 리스크 컨트롤

**전송 전에 주문 크기를 확인하십시오.** `POST /api/perpetuals/account/max-order-size`는 주어진 `marketId`와 `side`(`0` 매수, `1` 매도)에 대해 현재 리스크 한도에서 계정이 낼 수 있는 최대 주문 크기를 반환합니다. 실패한 트랜잭션으로 한도를 확인하지 말고, 호가 크기를 키우거나 레버리지를 바꾸기 전에 호출하십시오.

**데드맨 스위치는 없습니다.** API에는 예약 취소나 연결 끊김 시 자동 만료 엔드포인트가 없습니다. 프로세스가 죽으면 호가는 오더북에 남습니다. 전략 루프가 멈추면 모든 미체결 주문을 취소하는 하트비트 킬 스위치를 만들고, 하트비트 타임아웃뿐 아니라 `SIGINT`/`SIGTERM`에도 연결하십시오. 종료 전에 취소가 반영되었는지 확인하십시오.

**계정 상태는 즉시 낡습니다.** 체결, 취소, 입금, 출금, 레버리지 변경이 있으면 다음 호가를 계산하기 전에 계정과 포지션 상태를 갱신하십시오.

**같은 코인 객체를 건드리는 작업은 직렬화하십시오.** 동시에 서명된 트랜잭션들이 같은 USDC 코인이나 가스 코인을 두고 경합하면 버전 오류나 이중 서명(equivocation) 오류로 실패할 수 있습니다. 담보 작업은 직렬화하고, 병렬 제출자에게는 각자의 가스 코인을 주십시오.

## 가스 최적화

가장 큰 가스 절감은 트랜잭션 구성 방식에서 나옵니다. 별도 호출 대신 `cancel-and-place-orders`를 원자적으로 사용하면 트랜잭션을 따로 보내는 비용을 피하고, 낡은 호가 취소와 대체 주문 등록 사이의 공백도 없앨 수 있습니다.

**비효율: 별도 트랜잭션**

```
TX 1: cancel_orders              ← cancel stale quotes
TX 2: place_limit_order (×1)     ← place the replacement
────────────────────────────────────────────────
Result: two transactions, two computation minimums, and a gap between them
```

**효율: 배칭을 활용한 원자적 취소·등록**

```
TX 1:
  cancel_orders                  ← cancel stale quotes
  place_limit_order (×5)         ← 5 new orders
────────────────────────────────────────────────
Result: one atomic transaction and one computation minimum for the entire quote refresh
```

모든 Sui 트랜잭션은 최소 연산 1,000 단위를 지불하며, 이는 현재 기준 가스 가격 100 MIST에서 100,000 MIST(0.0001 SUI)입니다. 이 최솟값 안에 약 24개의 주문 작업(등록 또는 취소)이 들어가므로, 취소와 등록을 하나의 `cancel-and-place-orders` 호출로 묶으면 그 비용이 PTB 안의 모든 작업에 나뉩니다. 취소 두 건과 신규 지정가 주문 두 건으로 구성된 취소·등록 PTB는 **총 약 103,000 MIST(0.000103 SUI)**, 즉 **신규 주문당 약 0.0000515 SUI**가 듭니다.

이 수치는 Sui 프로토콜 139 이후인 2026-10-27에 기준 가스 가격 100 MIST에서 측정한 Sui 메인넷 관측 중앙값이며, 고정 수수료가 아닙니다. 순 가스는 연산 비용에 스토리지 비용을 더하고 스토리지 리베이트를 뺀 값이며, 연산 비용 부분은 가스 가격에 비례해 늘어납니다. 배치 크기별 주문 작업당 비용은 [마켓 메이커 경제성](https://docs.aftermath.finance/pages/tOIoJpvDjazVEBUw0EdX#%EA%B0%80%EC%8A%A4-%EB%B9%84%EC%9A%A9)을 참고하십시오.

### 팁

* **항상 `cancel-and-place-orders`를 사용하십시오.** 취소와 등록을 절대 별도 트랜잭션으로 보내지 마십시오.
* **취소와 등록을 한 호출로 배칭하십시오.** `ordersToPlace` 배열은 여러 주문을 받습니다. 주문 작업당 비용은 PTB당 약 24개 작업까지 크게 떨어집니다. 그 이상은 작업 하나당 약 4,300 MIST가 추가됩니다.
* **보증금을 고려해 가스 예산을 정하십시오.** 신규 주문마다 스토리지 보증금이 들며, 주문이 취소되거나 체결되면 환불되지만 가스 예산은 이를 선불로 감당해야 합니다. 큰 배치에는 더 큰 예산이 필요하지만, 주문이 취소되거나 체결되고 나면 순지출이 늘어나지는 않습니다. `sponsor.gasBudget`의 단위는 MIST입니다.
* **양쪽 호가를 한 트랜잭션에 담으십시오.** 매수와 매도 호가를 같은 `ordersToPlace` 배열에 넣으십시오.
* **포스트 온리(`orderType: 2`)를 사용하십시오.** 메이커 체결이 보장되고 테이커 수수료를 피할 수 있습니다.
* **주문에 `clientOrderId`를 태그하십시오.** 자신의 ID로 취소하고 조회 왕복을 생략하십시오.
* **에이전트 지갑을 사용하십시오.** `grant-agent-wallet`으로 서명을 에이전트 지갑에 위임해 메인 키를 콜드 상태로 유지하십시오. 에이전트 지갑은 거래는 할 수 있지만 담보 출금은 할 수 없습니다.
* **가스 풀 스폰서십을 사용하십시오.** 가스 풀(`/api/gas-pool/*`)에 미리 자금을 넣고 스폰서 지갑과 재사용 가능한 약관 서명을 전달하면 가스 비용을 예측할 수 있습니다.
* **`txKind`로 합성하십시오.** 기존 `TransactionKind`를 전달해 트랜잭션 두 개를 보내는 대신 리쿼트를 더 큰 PTB에 접어 넣으십시오.
* **오라클 업데이트를 직접 추가하지 마십시오.** API가 오라클 최신성을 내부에서 처리합니다.
* **대기열을 앞지르려고 가스를 과다 지불하지 마십시오.** 우선순위 가스 트랜잭션에는 추가 테이커 수수료(마켓 파라미터의 `priorityTakerFee`)가 부과되며, 해당 파라미터가 설정되지 않은 마켓에서는 아예 거부됩니다. [기준 가스 가격](https://docs.aftermath.finance/ko/perpetuals/architecture/fees/reference-gas-price.md)을 참고하십시오.

### CCXT

이미 CCXT 인프라로 운영 중인 회사라면 CCXT 표준 인터페이스도 지원합니다. [CCXT 문서](https://github.com/clawd-aftermath/aftermath-docs-translations/tree/ko/for-developers/api/ccxt.md)를 참고하십시오. 다만 CCXT 엔드포인트는 원시 `TransactionKind`가 아니라 `transactionBytes`와 `signingDigest`를 반환하므로 가스와 PTB 구성에 대한 제어가 줄어듭니다. `transactionBytes`가 아닌 `signingDigest`에 서명하고 `signatures[]`를 제출하십시오. 전송자와 가스 소유자가 다르면 두 서명 모두 이 배열에 들어갑니다.

CCXT의 `OrderRequest`는 네이티브 인터페이스보다 좁습니다. `timeInForce`와 `postOnly`는 `/api/ccxt/build/createOrders`에서 지원되지 않으며 전송해도 무시됩니다. 마켓 메이커는 포스트 온리로 호가를 내야 하므로 네이티브 엔드포인트를 사용하십시오.

전체 API 레퍼런스는 [Swagger 문서](https://aftermath.finance/docs)를 참고하십시오.
