> ## Documentation Index
> Fetch the complete documentation index at: https://docs.raydium.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 2026-05-18 — CLMM: 리미트 오더, 단측 수수료, 동적 수수료

> 세 가지 옵트인 방식의 하위 호환 CLMM 기능: 1급 리미트 오더, 단측 수수료 수집, 변동성 추적 동적 수수료 — 그리고 PoolState 재구성 및 새로운 에러 코드.

<Info>
  **이 페이지는 AI 자동 번역입니다. 모든 내용은 영문판을 기준으로 합니다.**

  [영문판 보기 →](/reference/changelog/2026-05-18-clmm-limit-orders)
</Info>

<Info>
  문서 변경 로그 항목입니다. 모든 업데이트의 색인은 [`reference/changelog`](/ko/reference/changelog)를 참고하세요. 프로토콜의 역사적 타임라인은 [`introduction/history-and-milestones`](/ko/introduction/history-and-milestones)를 참고하세요.
</Info>

다음 CLMM 릴리스는 세 가지 풀 레벨 기능을 추가합니다. 이들은 풀 생성 시점에 옵트인 방식이며 기존 풀 및 포지션과 하위 호환됩니다.

## 통합자를 위한 요약

* **리미트 오더**는 이제 1급 CLMM 프리미티브입니다. LP는 이를 지원하는 풀에서 단일 틱 오더를 열 수 있으며, 스왑이 틱을 지날 때 FIFO 방식으로 채워지고, 오프체인 키퍼(`limit_order_admin`)가 소유자가 온라인 상태가 아니어도 채워진 출력을 정산할 수 있습니다. 7개의 새로운 SDK 메서드(`openLimitOrder`, `increaseLimitOrder`, `decreaseLimitOrder`, `settleLimitOrder`, `closeLimitOrder`, `closeAllLimitOrder`, `settleAllLimitOrder`)와 `/limit-order/` 아래의 3개의 새로운 Temp API 엔드포인트(활성 오더, 사용자별 히스토리, PDA별 이벤트 로그)가 전체 흐름을 다룹니다.
* \*\*단측 수수료(`CollectFeeOn`)\*\*는 풀이 입력 측에서 스왑 수수료를 수집하거나(레거시, 모드 `0`), 항상 `token_0`에서(모드 `1`), 또는 항상 `token_1`에서(모드 `2`) 수집하도록 합니다. 페어의 한쪽이 정규 회계 토큰일 때 유용합니다.
* **동적 수수료**는 풀이 빠른 틱 이동으로 상승하고 시간에 따라 감소하는 변동성 추적 할증료를 옵트인하도록 합니다. 계층별 `DynamicFeeConfig`와 풀별 `DynamicFeeInfo`로 보정됩니다. 새로운 `/main/clmm-dynamic-config` 엔드포인트가 계층 목록을 제공합니다.
* 새로운 명령어 `CreateCustomizablePool`은 풀 생성 시점에 세 가지 옵션을 모두 노출합니다. 클래식 `CreatePool`은 기본 수수료, 리미트 오더 없는 풀에 계속 작동합니다.
* **인덱서 주요 변경**: `PoolState`의 방향별 거래량 카운터(`swap_in_amount_token_{0,1}`, `swap_out_amount_token_{0,1}`)와 생애 수수료 카운터(`total_fees_token_{0,1}`, `total_fees_claimed_token_{0,1}`)는 `fee_on`과 `dynamic_fee_info`를 위한 공간을 만들기 위해 패딩으로 폐기되었습니다. 이 필드를 직접 읽는 인덱서는 온체인 `Observation` 링 또는 API로 마이그레이션해야 합니다.

## 이것이 중요한 이유 (트레이더, LP, 통합자)

* **트레이더**는 롱테일 및 이벤트 기반 페어에서 더 타이트한 호가를 얻습니다: 동적 수수료는 풀이 LP가 범위를 적극적으로 확대할 필요 없이 테이커로부터 변동성 할증료를 흡수하도록 하며, 리미트 오더 래더는 범위 전체 자본을 약정하지 않고 특정 가격에서 온체인 유동성을 심화합니다.
* **LP**는 집중된 범위 및 풀 범위 포지션 외에 세 번째 전략을 얻습니다: 정확한 가격 오더를 주차하고, 가격이 방문할 때 채워지고, 인용 토큰으로 정산합니다. 채워진 부분에 대해 활성 리밸런싱이 필요하지 않습니다.
* **통합자**는 동적 수수료 풀을 결정론적으로 모델링할 수 있습니다 — 알고리즘과 매개변수는 완전히 온체인이고, 보정 계층은 쿼리 가능하며, 스왑 경로는 모양이 변하지 않습니다(각 단계의 수수료만 변합니다).

## 프로그램에서 변경된 사항

### 새로운 계정

* **`DynamicFeeConfig`** — 계층별 보정 레코드(필터 기간, 감소 기간, 감소 계수, 동적 수수료 제어, 최대 변동성 누적기). `CreateDynamicFeeConfig`(관리자)로 생성되고, 동적 수수료가 활성화될 때 `CreateCustomizablePool`에서 참조됩니다.
* **`LimitOrderState`** — 주문별 계정(PDA 시드: `[owner, limit_order_nonce, order_nonce]`) 풀, 틱, 측면, 입력 금액, 미채움 비율, FIFO 코호트 단계, 장부 스냅샷을 보유합니다. 생명주기는 암시적입니다(`filled_amount` vs `total_amount`, 계정 존재 여부): `Open → Filled → Settled → Closed`.
* **`LimitOrderNonce`** — (소유자, nonce\_index) 단조 증가 카운터로 리미트 오더 PDA 시드를 얻습니다. `nonce_index: u8`은 동일한 소유자가 오더를 최대 256개의 독립적인 논스 스트림으로 분할하도록 합니다.

[계정 → DynamicFeeConfig 및 DynamicFeeInfo](/ko/products/clmm/accounts) 및 [계정 → LimitOrderState](/ko/products/clmm/accounts)를 참고하세요.

### `PoolState` 재구성

| 필드 그룹       | 이전 레이아웃                                                                                                  | 새로운 레이아웃                                                     |
| ----------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
| 방향별 거래량 카운터 | `swap_in_amount_token_0`, `swap_out_amount_token_0`, `swap_in_amount_token_1`, `swap_out_amount_token_1` | `padding5: [u128; 4]`로 통합                                    |
| 생애 수수료 카운터  | `total_fees_token_0`, `total_fees_claimed_token_0`, `total_fees_token_1`, `total_fees_claimed_token_1`   | `padding6: [u64; 4]`로 통합                                     |
| 단측 수수료      | —                                                                                                        | `fee_on: u8` (0 = FromInput, 1 = Token0Only, 2 = Token1Only) |
| 동적 수수료      | —                                                                                                        | `dynamic_fee_info: DynamicFeeInfo` (임베드됨)                    |

총 계정 크기는 변하지 않습니다. **인덱서**: 거래량 추적을 `PoolState`에서 `Observation` 링 또는 API로 전환하세요. 폐기된 카운터는 기존 풀에서 0으로 설정되지 않습니다(마지막으로 수행한 값을 보유함). 따라서 업그레이드 후 다시 읽으면 오래된 데이터가 반환됩니다.

### `TickState` 추가 (주요 변경 없음)

4개의 새로운 필드가 `TickState`의 끝에 추가되어 일부 후행 패딩을 대체합니다:

* `order_phase: u64` — 이 틱에서 리미트 오더 코호트를 구분하는 카운터.
* `orders_amount: u64` — 이 틱의 모든 열린 오더에 의해 약정된 총 입력(모두 완전히 미채움은 아님).
* `part_filled_orders_remaining: u64` — 현재 스왑에 의해 소비되는 코호트에서 여전히 미채움 입력.
* `unfilled_ratio_x64: u128` — 각 오더의 채움 공유를 계산하는 데 사용되는 Q64.64 비율.

틱 배열 레이아웃, 크기 및 PDA 시드는 변하지 않습니다.

### 새로운 명령어

* **`CreateDynamicFeeConfig` (관리자)** — 보정된 `DynamicFeeConfig` 계층을 생성합니다. 권한: `CreateAmmConfig`와 동일한 재무 멀티시그.
* **`UpdateDynamicFeeConfig` (관리자)** — 기존 계층의 매개변수를 업데이트합니다.
* **`CreateCustomizablePool`** — `collect_fee_on`, `enable_dynamic_fee`, `dynamic_fee_config`를 노출하는 풀 생성 진입점. `CreatePool`과 공존합니다. 새로운 옵션이 필요한 모든 풀에 `CreateCustomizablePool`을 권장합니다.
* **`OpenLimitOrder`** — 단일 틱 리미트 오더를 엽니다. `LimitOrderNonce`를 범프하고, `LimitOrderState`를 할당하고, 틱의 FIFO 코호트에 오더를 슬롯합니다.
* **`IncreaseLimitOrder` / `DecreaseLimitOrder`** — 오더의 미채움 부분을 조정합니다. 완전히 채워진 오더에서 `InvalidOrderPhase`로 되돌립니다.
* **`SettleLimitOrder`** — 채워진 출력을 소유자의 ATA로 스윕합니다. 호출자는 소유자 또는 풀의 `limit_order_admin` 키퍼일 수 있습니다.
* **`CloseLimitOrder`** — 완전히 정산된 오더를 닫아 임차료를 회수합니다.

### `SwapV2` 동작 변경

스왑 경로 자체는 모양이 변하지 않지만, 경로를 따라 3가지가 이제 발생합니다:

1. **동적 수수료**(활성화된 경우): 풀의 `DynamicFeeInfo`는 각 단계에서 업데이트되고(감소 → 누적 → 상한), 결과 할증료는 해당 단계의 기본 수수료 위에 추가됩니다.
2. **리미트 오더 매칭**(단계가 열린 오더가 있는 초기화된 틱을 지날 때): 스왑 입력의 일부는 FIFO로 소비되어 해당 틱의 코호트를 채우고, `unfilled_ratio_x64`는 원자적으로 업데이트됩니다.
3. **단측 수수료 라우팅**(`fee_on != 0`일 때): 수수료는 스왑 방향에 관계없이 `token_0` 또는 `token_1`에서 가져오며, 항상 입력 측에서 가져오는 대신입니다.

이들 각각은 풀이 레거시 기본값으로 생성되었을 때 작동하지 않습니다. [명령어 → SwapV2](/ko/products/clmm/instructions)에서 업데이트된 상태 변경 매트릭스를 참고하세요.

### 새로운 에러 코드

`ErrorCode` 열거형은 이 릴리스에서 다시 번호가 매겨졌습니다: 5개의 레거시 변형(`LOK`, `ZeroMintAmount`, `InvalidLiquidity`, `TransactionTooOld`, `InvalidRewardDesiredAmount`)이 제거되었고, 11개의 새로운 변형이 추가되었습니다. Anchor가 열거형 순서에서 `6000`부터 에러를 번호 매기기 때문에, **제거된 위치 이상의 모든 에러 코드가 이동했습니다** — 숫자 코드를 하드코딩한 클라이언트는 다시 매핑해야 합니다.

새로운 코드는:

* `6040` `OrderAlreadyFilled`
* `6041` `InvalidOrderPhase`
* `6042` `InvalidLimitOrderAmount`
* `6043` `OrderPhaseSaturated`
* `6044` `InvalidDynamicFeeConfigParams`
* `6045` `InvalidFeeOn`
* `6046` `ZeroSqrtPrice`
* `6047` `ZeroLiquidity`
* `6048` `MissingBaseFlag`
* `6049` `MissingMintAccount`
* `6050` `MissingTokenProgram2022`

전체 문자열과 모든 CLMM 에러의 이동 후 테이블은 [에러 코드](/ko/reference/error-codes)에 있습니다.

## SDK에서 변경된 사항 (`@raydium-io/raydium-sdk-v2`)

* **`raydium.clmm`의 새로운 메서드**: `createCustomizablePool`, `openLimitOrder`, `increaseLimitOrder`, `decreaseLimitOrder`, `settleLimitOrder`, `settleAllLimitOrder`, `closeLimitOrder`, `closeAllLimitOrder`.
* **`raydium.api`의 새로운 REST 헬퍼**: `getClmmDynamicConfigs`, `getClmmLimitOrderConfigs`.
* **새로운 타입**: `CollectFeeOn` 열거형, `DynamicFeeConfig`, `DynamicFeeInfo`, `LimitOrderState`, `LimitOrderConfig`.
* **내부 재구성**: `utils/`가 `libraries/`로 이동했습니다. 패키지 배럴은 변하지 않습니다. `@raydium-io/raydium-sdk-v2/utils/...` 아래의 깊은 임포트만 `…/libraries/...`로 업데이트하면 됩니다.

엔드투엔드 TypeScript 워크스루는 [`products/clmm/code-demos`](/ko/products/clmm/code-demos)에 있습니다.

## API에서 변경된 사항

* `api-v3` — `/main/` 아래의 2개의 새로운 엔드포인트:
  * `GET /main/clmm-dynamic-config` — `DynamicFeeConfig` 계층 목록.
  * `GET /main/clmm-limit-order-config` — 풀별 리미트 오더 구성.
* `temp-api-v1` — `/limit-order/` 아래의 3개의 새로운 엔드포인트:
  * `GET /limit-order/order/list?wallet=…` — 지갑의 현재 주차된 오더(열림 및 부분 채움, 인덱서의 Redis 캐시에서 제공; 동일한 페이로드는 `totalAmount` / `filledAmount` / `pendingSettle`을 통해 두 단계를 모두 다룸).
  * `GET /limit-order/history/order/list-by-user?wallet=…` — 지갑의 역사적 리미트 오더. 선택적 필터: `poolId`, `mint1`, `mint2`, `hideCancel`. `nextPageId` / `size`(최대 100)를 통해 커서 페이지네이션됨.
  * `GET /limit-order/history/event/list-by-pda?pda=…` — PDA별 이벤트 로그(`open` / `increase` / `decrease` / `settle` / `close`) 하나 이상의 쉼표로 구분된 리미트 오더 PDA. `nextPageId` / `size`(최대 100)를 통해 커서 페이지네이션됨.

모두 5개는 API 참조 탭에 문서화되어 있습니다.

## 권한 표면

`limit_order_admin`은 오프체인 운영 키퍼이며, **멀티시그가 아닙니다**. 기존 오더에서만 `SettleLimitOrder`와 `CloseLimitOrder`를 호출할 수 있으며, 정산의 출력은 항상 **소유자의** ATA에 도달합니다. 풀 필드를 변경하거나, 오더를 열거나 수정하거나, 다른 것에 서명할 수 없습니다. [관리자 키 및 멀티시그 → CLMM](/ko/security/admin-and-multisig)을 참고하세요.

## 업데이트된 페이지

* `products/clmm/overview` — 새로운 "What's new" 섹션 및 업데이트된 다음 단계 포인터.
* `products/clmm/accounts` — 3개의 새로운 계정, `PoolState` 재구성 및 마이그레이션 경고, `TickState` 추가, 새로운 PDA 헬퍼.
* `products/clmm/instructions` — 7개의 새로운 명령어, `SwapV2` 동작 부록, 업데이트된 상태 변경 매트릭스.
* `products/clmm/fees` — 단측 수수료 섹션, 매개변수 테이블이 있는 동적 수수료 섹션.
* `products/clmm/math` — 리미트 오더 매칭 의사 코드, 동적 수수료 유도.
* `products/clmm/code-demos` — `createCustomizablePool` 데모, 전체 리미트 오더 워크스루, 새로운 함정.
* `algorithms/clmm-math` — 다중 틱 스왑 루프의 리미트 오더 매칭 및 동적 수수료에 대한 교차 참조.
* `sdk-api/typescript-sdk` — CLMM 모듈 추가 섹션, `utils/` → `libraries/` 마이그레이션 노트.
* `api-reference/openapi/api-v3.yaml` — 응답 스키마가 있는 2개의 새로운 엔드포인트.
* `api-reference/openapi/temp-api-v1.yaml` — 3개의 새로운 리미트 오더 엔드포인트(`/limit-order/order/list`, `/limit-order/history/order/list-by-user`, `/limit-order/history/event/list-by-pda`) 및 요청 및 응답 스키마.
* `api-reference/api-v3/overview` — 새로운 CLMM 구성 엔드포인트에 대한 노트.
* `api-reference/temp-api-v1/overview` — 새로운 활성 오더, 사용자별 히스토리, PDA별 이벤트 엔드포인트에 대한 노트.
* `reference/error-codes` — 11개의 새로운 CLMM 에러 코드(6040–6050) 및 5개의 제거된 레거시 코드; 제거 지점 이후의 숫자 코드가 이동했습니다.
* `security/admin-and-multisig` — 새로운 `DynamicFeeConfig` 관리자 행 및 `limit_order_admin` 키퍼 행, 제한된 권한 설명자 포함.

**검증 대상**:

* `raydium-clmm` 소스.
* `@raydium-io/raydium-sdk-v2` 소스.
* `api-v3` 및 `temp-api-v1` 소스.