# Pools SDK *[Documentation index](/llms.txt) ยท [Full index](/llms-full.txt)* Pools are shared objects that represent a market. See [Query the Pool](/onchain-finance/deepbookv3/contract-information/query-the-pool) for more information on pools. ## Pool functions The DeepBookV3 SDK exposes functions that you can call to read the state of a pool. These functions typically require a `managerKey`, `coinKey`, `poolKey`, or a combination of these. For details on these keys, see [DeepBookV3 SDK](/onchain-finance/deepbookv3-sdk#keys). The SDK includes some default keys that you can view in the `constants.ts` file. :::tip SDK unit handling Input amounts, quantities, and prices should be provided in standard decimal format (such as `10.5` SUI or `0.00001` nBTC). The SDK handles conversion to base units internally. Returned amounts are also in standard decimal format. ::: ### account Use `account` to retrieve the account information for a `BalanceManager` in a pool, which has the following form: ```ts { epoch: '511', open_orders: { constants: [ '170141211130585342296014727715884105730', '18446744092156295689709543266', '18446744092156295689709543265' ] }, taker_volume: 0, maker_volume: 0, active_stake: 0, inactive_stake: 0, created_proposal: false, voted_proposal: null, unclaimed_rebates: { base: 0, quote: 0, deep: 0 }, settled_balances: { base: 0, quote: 0, deep: 0 }, owed_balances: { base: 0, quote: 0, deep: 0 } } ``` **Parameters** - `poolKey`: String that identifies the pool to query. - `balanceManagerKey`: key of the balance manager defined in the SDK. ### accountOpenOrders Use `accountOpenOrders` to retrieve open orders for the balance manager and pool with the IDs you provide. The call returns a `Promise` that contains an array of open order IDs. **Parameters** - `poolKey`: String that identifies the pool to query. - `managerKey`: String that identifies the balance manager to query. ### checkManagerBalance Use `checkManagerBalance` to check the balance manager for a specific coin. The call returns a `Promise` in the form: ``` { coinType: string, balance: number } ``` **Parameters** - `managerKey`: String that identifies the balance manager to query. - `coinKey`: String that identifies the coin to query the balance of. ### getOrder Use `getOrder` to retrieve an order's information. The call returns a `Promise` in the `Order` struct, which has the following form: ```ts { balance_manager_id: { bytes: '0x6149bfe6808f0d6a9db1c766552b7ae1df477f5885493436214ed4228e842393' }, order_id: '9223372036873222552073709551614', client_order_id: '888', quantity: '50000000', filled_quantity: '0', fee_is_deep: true, order_deep_price: { asset_is_base: false, deep_per_asset: '0' }, epoch: '440', status: 0, expire_timestamp: '1844674407370955161' } ``` **Parameters** `poolKey`: String that identifies the pool to query. `orderId`: ID of the order to query. ### getQuoteQuantityOut Use `getQuoteQuantityOut` to retrieve the quote quantity out for the base quantity you provide. The call returns a `Promise` in the form: ``` { baseQuantity: number, baseOut: number, quoteOut: number, deepRequired: number } ``` where `deepRequired` is the amount of DEEP required for the dry run. **Parameters** - `poolKey`: String that identifies the pool to query. - `baseQuantity`: Number that defines the base quantity you want to convert. ### getBaseQuantityOut Use `getBaseQuantityOut` to retrieve the base quantity out for the quote quantity that you provide. The call returns a `Promise` in the form: ``` { quoteQuantity: number, baseOut: number, quoteOut: number, deepRequired: number } ``` where `deepRequired` is the amount of DEEP required for the dry run. **Parameters** - `poolKey`: String that identifies the pool to query. - `quoteQuantity`: Number that defines the quote quantity you want to convert. ### getQuantityOut Use `getQuantityOut` to retrieve the output quantities for the base or quote quantity you provide. You provide values for both quantities, but only one of them can be nonzero. The call returns a `Promise` with the form: ``` { baseQuantity: number, quoteQuantity: number, baseOut: number, quoteOut: number, deepRequired: number } ``` where `deepRequired` is the amount of DEEP required for the dry run. **Parameters** - `poolKey`: String that identifies the pool to query. - `baseQuantity`: Number that defines the base quantity you want to convert. Set to `0` if using quote quantity. - `quoteQuantity`: Number that defines the quote quantity you want to convert. Set to `0` if using base quantity. ### getLevel2Range Use `getLevel2Range` to retrieve level 2 order book within the boundary price range you provide. The call returns a `Promise` in the form: ``` { prices: Array, quantities: Array } ``` **Parameters** - `poolKey`: String that identifies the pool to query. - `priceLow`: Number for lower bound of price range. - `priceHigh`: Number for upper bound of price range. - `isBid`: Boolean when set to `true` gets bid orders, else retrieve ask orders. ### getLevel2TicksFromMid Use `getLevel2TicksFromMid` to retrieve level 2 order book ticks from mid-price for a pool with the ID you provide. The call returns a `Promise` in the form: ```ts { bid_prices: Array, bid_quantities: Array, ask_prices: Array, ask_quantities: Array } ``` **Parameters** - `poolKey`: String that identifies the pool to query. - `ticks`: Number of ticks from mid-price. ### lockedBalance Use `lockedBalance` to retrieve a `BalanceManager` locked balance in the pool. The call returns a `Promise` in the `Order` struct, which has the following form: ```ts { base: 5.5, quote: 2, deep: 0.15, } ``` **Parameters** `poolKey`: String that identifies the pool to query. `balanceManagerKey`: key of the balance manager defined in the SDK. ### poolTradeParams Use `poolTradeParams` to retrieve the trade params for the pool, which has the following form: ```ts { takerFee: 0.001, makerFee: 0.0005, stakeRequired: 100, } ``` **Parameters** - `poolKey`: String that identifies the pool to query. ### vaultBalances Use `vaultBalances` to get the vault balances for a pool with the ID you provide. The call returns a `Promise` in the form: ```ts { base: number, quote: number, deep: number } ``` **Parameters** - `poolKey`: String that identifies the pool to query. ### getPoolIdByAssets Use `getPoolIdByAssets` to retrieve the pool ID for the asset types you provide. The call returns a `Promise` with the address of the pool if it's found. **Parameters** - `baseType`: String of the type of base asset. - `quoteType`: String of the type of quote asset. ### midPrice Use `midPrice` to retrieve the mid price for a pool with the ID that you provide. The call returns a `Promise` with the mid price. **Parameters** - `poolKey`: String that identifies the pool to query. ### `whitelisted` Use `whitelisted` to check if the pool with the ID you provide is whitelisted. The call returns a `Promise` as a boolean indicating whether the pool is whitelisted. **Parameters** - `poolKey`: String that identifies the pool to query. ### `poolBookParams` Use `poolBookParams` to retrieve the book parameters for a pool, including tick size, lot size, and min size. The call returns a `Promise` with the book parameters. **Parameters** - `poolKey`: String that identifies the pool to query. ### `getOrders` Use `getOrders` to retrieve multiple orders from a pool. The call returns a `Promise` with an array of order information. **Parameters** - `poolKey`: String that identifies the pool to query. - `orderIds`: Array of strings representing the order IDs to retrieve. ### `getPoolDeepPrice` Use `getPoolDeepPrice` to get the DEEP price conversion for a pool. The call returns a `Promise` with the DEEP price information. **Parameters** - `poolKey`: String that identifies the pool to query. ## Administrative functions The SDK provides administrative functions for pool management. ### `addDeepPricePoint` Use `addDeepPricePoint` to add a DEEP price point for a target pool using a reference pool. The call returns a function that takes a `Transaction` object. **Parameters** - `targetPoolKey`: String that identifies the target pool. - `referencePoolKey`: String that identifies the reference pool. ### `updatePoolAllowedVersions` Use `updatePoolAllowedVersions` to update the allowed package versions for a pool. The call returns a function that takes a `Transaction` object. **Parameters** - `poolKey`: String that identifies the pool. ### `createPermissionlessPool` Use `createPermissionlessPool` to create a new permissionless pool. The call returns a function that takes a `Transaction` object. **Parameters** - `params`: `CreatePermissionlessPoolParams` object containing: - `baseCoinKey`: String that identifies the base coin. - `quoteCoinKey`: String that identifies the quote coin. - `tickSize`: Number representing the tick size. - `lotSize`: Number representing the lot size. - `minSize`: Number representing the minimum order size. - `deepCoin`: Optional `TransactionArgument` for DEEP token payment. ### `getBalanceManagerIds` Use `getBalanceManagerIds` to get all balance manager IDs for a specific owner. The call returns a `Promise` with an array of balance manager IDs. **Parameters** - `owner`: String representing the owner address. ## Referral functions The SDK provides functions to manage referrals and earn referral fees from trading activity. ### `mintReferral` Use `mintReferral` to create a new referral for a pool with a specified multiplier. The multiplier determines what percentage of trading fees are allocated to the referrer. The call returns a function that takes a `Transaction` object. **Parameters** - `poolKey`: String that identifies the pool. - `multiplier`: Number representing the referral multiplier (such as 0.1 for 10%). ### `updateReferralMultiplier` Use `updateReferralMultiplier` to update the multiplier for an existing referral. Only the referral owner can update the multiplier. The call returns a function that takes a `Transaction` object. **Parameters** - `poolKey`: String that identifies the pool. - `referral`: String representing the referral ID. - `multiplier`: Number representing the new referral multiplier. ### `claimReferralRewards` Use `claimReferralRewards` to claim accumulated referral fees. Returns an object with `baseRewards`, `quoteRewards`, and `deepRewards`. The call returns a function that takes a `Transaction` object. **Parameters** - `poolKey`: String that identifies the pool. - `referral`: String representing the referral ID. ### `getReferralBalances` Use `getReferralBalances` to view the current accumulated balances for a referral without claiming them. The call returns a `Promise` with the balances in base, quote, and DEEP tokens. **Parameters** - `poolKey`: String that identifies the pool. - `referral`: String representing the referral ID.