Orders

The pool_proxy module provides wrapper functions for trading with margin managers. These functions enable placing orders, modifying and canceling them, and managing staking and governance participation through a margin manager. All trading operations require the margin manager to be associated with the correct DeepBook pool. To place orders, call the _v2 functions in the pool_proxy_upgraded module; modify, cancel, settlement, staking, governance, and rebate functions are in pool_proxy.

What are margin orders in DeepBook?

Margin orders in DeepBook are trading instructions placed through a margin manager rather than a standard balance manager. The margin manager holds your collateral and tracks your debt, and the pool_proxy module routes orders through it to the underlying DeepBook pool.

There are two primary order types:

Limit orders execute at a specified price or better. The order rests in the order book until it fills or you cancel it.
Market orders execute immediately at the best available prices. They do not rest in the order book.

Regular limit and market orders require margin trading to be enabled for the pool, and abort with EPoolNotEnabledForMarginTrading otherwise. When the margin manager carries debt, the order must also leave the post-trade risk ratio at or above the pool's minimum open risk ratio.

Reduce-only orders are a variant of both types. Reduce-only is a direction guard rather than a size limit: a bid requires base (short-side) debt, and an ask requires quote (long-side) debt and can sell up to the base the manager holds. The order must also leave the post-trade risk ratio no worse than it was before the trade. Reduce-only orders skip the margin-trading-enabled check, so you can still wind a position down after an admin disables margin trading for the pool. Reduce-only limit orders additionally require the manager to be at or above the liquidation risk ratio when placed (EReduceOnlyBelowLiquidation). A manager that is already liquidatable closes through place_reduce_only_market_order_and_repay_loan instead, or is liquidated.

Placing an order does not itself borrow, and debt otherwise changes only through the borrow_* and repay_* functions on the margin manager. To close a position and repay in the same call, use place_reduce_only_market_order_and_repay_loan or place_reduce_only_limit_order_and_repay_loan.

How do I place an order using a margin manager?

Call place_limit_order_v2 or place_market_order_v2 in the pool_proxy_upgraded module, passing the margin registry, your margin manager, the DeepBook pool, both margin pools, and the base and quote PriceInfoObjects from Pyth's upgraded package (pyth_upgraded::price_info::PriceInfoObject). That is a different Move type from the legacy Pyth PriceInfoObject, so legacy price objects won't type-check. The margin manager checks ownership against the transaction sender, so there is no capability object to pass.

The following example shows how to call place_limit_order_v2 in a Move transaction:

use deepbook_margin::pool_proxy_upgraded;

// Place a limit order through a margin manager
pool_proxy_upgraded::place_limit_order_v2(
    registry,
    margin_manager,
    pool,
    base_margin_pool,
    quote_margin_pool,
    base_oracle,
    quote_oracle,
    client_order_id,
    order_type,
    self_matching_option,
    price,
    quantity,
    is_bid,
    pay_with_deep,
    expire_timestamp,
    clock,
    ctx,
);

To place a reduce-only order, call place_reduce_only_limit_order_v2 or place_reduce_only_market_order_v2 instead. Both apply the reduce-only direction guard, and the limit variant additionally requires the manager to be at or above the liquidation risk ratio when placed (EReduceOnlyBelowLiquidation).

info

The original place_limit_order, place_market_order, and place_reduce_only_* entries in pool_proxy abort with EDeprecatedUseV2. pool_proxy also has _v2 twins that read the legacy Pyth feed. They still work in the deployed package but are being retired, so call the _v2 functions in pool_proxy_upgraded instead.

How do I modify or cancel an order?

Use modify_order to reduce the quantity of a resting limit order. The new quantity must be lower than the original, otherwise the call aborts with ENewQuantityMustBeLessThanOriginal. Provide the order ID returned when you placed the order.

To cancel orders, use one of three functions depending on scope:

cancel_order cancels a single order by ID.
cancel_orders cancels a list of orders by ID.
cancel_all_orders cancels every open order for the margin manager in the pool.

How do I withdraw funds after a trade?

Settled amounts flow back into the margin manager's balance manager on the manager's next order, modify, or cancel in that pool. Call withdraw_settled_amounts to settle without placing another order. Anyone can call withdraw_settled_amounts_permissionless to settle on behalf of a margin manager they do not own.

API

Following are the different public functions for managing orders with margin managers.

Click to open

Place orders

Place limit and market orders through a margin manager. These entries require margin trading to be enabled for the pool, and abort with EPoolNotEnabledForMarginTrading otherwise.

File not found in manifest: packages/deepbook_margin/sources/pool_proxy_upgraded.move. You probably need to run `pnpm prebuild` and restart the site.

Click to open

Place reduce-only orders

Place reduce-only orders, which trade only in the direction that unwinds an existing debt. These orders are useful when margin trading is disabled and you need to close existing positions.

File not found in manifest: packages/deepbook_margin/sources/pool_proxy_upgraded.move. You probably need to run `pnpm prebuild` and restart the site.

Click to open

Close a position and repay in one call

Place a reduce-only order and repay the loan with the proceeds in the same call. The post-repay risk ratio must be at least the pre-trade ratio.

File not found in manifest: packages/deepbook_margin/sources/pool_proxy_upgraded.move. You probably need to run `pnpm prebuild` and restart the site.

Click to open

Modify order

Modify an existing order by reducing its quantity.