# Orders SDK

*[Documentation index](/llms.txt) · [Full index](/llms-full.txt)*

Placing and managing orders through margin managers enables leveraged trading on DeepBook. The Orders SDK provides functions for placing limit and market orders, managing positions, and participating in governance.

## Order functions

The DeepBook Margin SDK provides the following functions for managing orders through margin managers.

### `placeLimitOrder`

Use `placeLimitOrder` to place a limit order through a margin manager. The call returns a function that takes a `Transaction` object.

**Parameters**

- `params`: `PlaceMarginLimitOrderParams` object containing:
  - `poolKey`: String that identifies the DeepBook pool
  - `marginManagerKey`: String that identifies the margin manager
  - `clientOrderId`: String for the client-side order ID
  - `price`: Number representing the order price
  - `quantity`: Number representing the order quantity
  - `isBid`: Boolean indicating if this is a buy order
  - `expiration`: Optional number for order expiration timestamp
  - `orderType`: Optional `OrderType` enum
  - `selfMatchingOption`: Optional `SelfMatchingOptions` enum
  - `payWithDeep`: Optional boolean to pay fees with DEEP tokens

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `placeMarketOrder`

Use `placeMarketOrder` to place a market order through a margin manager. The call returns a function that takes a `Transaction` object.

**Parameters**

- `params`: `PlaceMarginMarketOrderParams` object containing similar parameters to limit orders (without price and expiration).

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `placeReduceOnlyLimitOrder`

Use `placeReduceOnlyLimitOrder` to place a limit order that can only reduce your existing debt position. Useful when margin trading is disabled and you need to close positions. The call returns a function that takes a `Transaction` object.

**Parameters**

- `params`: `PlaceMarginLimitOrderParams` object (same as `placeLimitOrder`).

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `placeReduceOnlyMarketOrder`

Use `placeReduceOnlyMarketOrder` to place a market order that can only reduce your existing debt position. The call returns a function that takes a `Transaction` object.

**Parameters**

- `params`: `PlaceMarginMarketOrderParams` object (same as `placeMarketOrder`).

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `modifyOrder`

Use `modifyOrder` to modify the quantity of an existing order. The call returns a function that takes a `Transaction` object.

:::warning
The `orderId` is the protocol `orderId` generated during order placement, which is different from the client `orderId`.
:::

**Parameters**

- `marginManagerKey`: String that identifies the margin manager.
- `orderId`: String of the protocol order ID.
- `newQuantity`: Number representing the new order quantity.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `cancelOrder`, `cancelOrders`, `cancelAllOrders`

Use these functions to cancel orders for a margin manager. The call returns a function that takes a `Transaction` object.

**Parameters**

- `marginManagerKey`: String that identifies the margin manager.
- `orderId` (cancelOrder only): String of the protocol order ID.
- `orderIds` (cancelOrders only): Array of protocol order IDs.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `withdrawSettledAmounts`

Use `withdrawSettledAmounts` to withdraw settled amounts from completed trades. The call returns a function that takes a `Transaction` object.

**Parameters**

- `marginManagerKey`: String that identifies the margin manager.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `stake`, `unstake`

Use these functions to stake and unstake DEEP tokens through the margin manager for trading fee benefits. The call returns a function that takes a `Transaction` object.

**Parameters**

- `marginManagerKey`: String that identifies the margin manager.
- `stakeAmount` (stake only): Number representing the amount to stake.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `submitProposal`, `vote`

Use these functions to participate in pool governance through the margin manager. The call returns a function that takes a `Transaction` object.

**Parameters**

- `marginManagerKey`: String that identifies the margin manager.
- `params` (submitProposal): `MarginProposalParams` object with `takerFee`, `makerFee`, and `stakeRequired`.
- `proposalId` (vote): String representing the proposal ID.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `claimRebate`

Use `claimRebate` to claim trading rebates earned through the margin manager. The call returns a function that takes a `Transaction` object.

**Parameters**

- `marginManagerKey`: String that identifies the margin manager.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `withdrawMarginSettledAmounts`

Use `withdrawMarginSettledAmounts` to permissionlessly withdraw settled amounts for any margin manager by its object ID. Unlike `withdrawSettledAmounts` which requires ownership, this can be called by anyone. The call returns a function that takes a `Transaction` object.

**Parameters**

- `poolKey`: String that identifies the DeepBook pool.
- `marginManagerId`: String representing the object ID of the margin manager.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

### `updateCurrentPrice`

Use `updateCurrentPrice` to update the current price for a pool using the Pyth oracle. The call returns a function that takes a `Transaction` object.

**Parameters**

- `poolKey`: String that identifies the DeepBook pool.

<!-- External code reference: packages/deepbook-v3/src/transactions/poolProxy.ts -->

## Examples

The following examples demonstrate common margin order operations.

### Place a limit order

```tsx
// Params for limit order
interface PlaceMarginLimitOrderParams {
	poolKey: string;
	marginManagerKey: string;
	clientOrderId: string;
	price: number;
	quantity: number;
	isBid: boolean;
	expiration?: number | bigint;
	orderType?: OrderType;
	selfMatchingOption?: SelfMatchingOptions;
	payWithDeep?: boolean;
}

// Example: Place a buy limit order for 10 SUI at $2.50
placeLimitOrder = (tx: Transaction) => {
	const poolKey = 'SUI_DBUSDC';
	const managerKey = 'MARGIN_MANAGER_1';
	tx.add(
		this.poolProxyContract.placeLimitOrder({
			poolKey,
			marginManagerKey: managerKey,
			clientOrderId: '12345',
			price: 2.5,
			quantity: 10,
			isBid: true,
			payWithDeep: true,
		}),
	);
};
```

### Place a market order

```tsx
// Example: Place a market sell order for 5 SUI
placeMarketOrder = (tx: Transaction) => {
	const poolKey = 'SUI_DBUSDC';
	const managerKey = 'MARGIN_MANAGER_1';
	tx.add(
		this.poolProxyContract.placeMarketOrder({
			poolKey,
			marginManagerKey: managerKey,
			clientOrderId: '12346',
			quantity: 5,
			isBid: false,
			payWithDeep: true,
		}),
	);
};
```

### Place a reduce-only order

```tsx
// Example: Place a reduce-only limit order to close a position
placeReduceOnly = (tx: Transaction) => {
	const poolKey = 'SUI_DBUSDC';
	const managerKey = 'MARGIN_MANAGER_1';
	tx.add(
		this.poolProxyContract.placeReduceOnlyLimitOrder({
			poolKey,
			marginManagerKey: managerKey,
			clientOrderId: '12347',
			price: 2.6,
			quantity: 10,
			isBid: true, // Buying back to reduce short position
			payWithDeep: true,
		}),
	);
};
```

### Modify and cancel orders

```tsx
// Example: Modify order quantity
modifyExistingOrder = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	const orderId = '123456789'; // Protocol order ID
	const newQuantity = 8; // Reduce from 10 to 8
	tx.add(this.poolProxyContract.modifyOrder(managerKey, orderId, newQuantity));
};

// Example: Cancel a single order
cancelSingleOrder = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	const orderId = '123456789';
	tx.add(this.poolProxyContract.cancelOrder(managerKey, orderId));
};

// Example: Cancel multiple orders
cancelMultipleOrders = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	const orderIds = ['123456789', '987654321'];
	tx.add(this.poolProxyContract.cancelOrders(managerKey, orderIds));
};

// Example: Cancel all orders
cancelAll = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	tx.add(this.poolProxyContract.cancelAllOrders(managerKey));
};
```

### Stake and participate in governance

```tsx
// Example: Stake DEEP tokens
stakeDeep = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	const stakeAmount = 1000; // Stake 1000 DEEP
	tx.add(this.poolProxyContract.stake(managerKey, stakeAmount));
};

// Example: Submit a governance proposal
submitGovernanceProposal = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	tx.add(
		this.poolProxyContract.submitProposal(managerKey, {
			takerFee: 0.0005, // 5 bps
			makerFee: 0.0002, // 2 bps
			stakeRequired: 1000,
		}),
	);
};

// Example: Vote on a proposal
voteOnProposal = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	const proposalId = '0x...';
	tx.add(this.poolProxyContract.vote(managerKey, proposalId));
};

// Example: Claim trading rebates
claimTradingRebate = (tx: Transaction) => {
	const managerKey = 'MARGIN_MANAGER_1';
	tx.add(this.poolProxyContract.claimRebate(managerKey));
};
```