Skip to main content

Pools SDK

Pools are shared objects that represent a market. See 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. The SDK includes some default keys that you can view in the constants.ts file.

SDK Unit Handling

Input amounts, quantities, and prices should be provided in standard decimal format (e.g., 10.5 SUI, 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:

{
  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:

{
  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 non-zero. 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<number>,
  quantities: Array<number>
}

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:

{
  bid_prices: Array<number>,
  bid_quantities: Array<number>,
  ask_prices: Array<number>,
  ask_quantities: Array<number>
}

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:

{
  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:

{
  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:

{
  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 (e.g., 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.