Skip to main content

BalanceManager SDK

The BalanceManager is a core component of DeepBookV3 that holds all asset balances. The SDK provides comprehensive functions to create, manage, and interact with balance managers.

Most functions on this page identify a balance manager by managerKey, a string that identifies the balance manager. The trade proof functions generateProofAsOwner and generateProofAsTrader instead take managerId, the ID of the balance manager. Use id to get the ID of a balance manager from its managerKey.

A tradeCap is a capability object that you mint for a balance manager with mintTradeCap and transfer to a trader, as in the Mint and use capabilities example. The holder uses it to generate trade proofs with generateProofAsTrader. The referral functions also require a tradeCap for permission checking. Similarly, you use a depositCap with depositWithCap and a withdrawCap with withdrawWithCap.

Balance manager functions​

The DeepBookV3 SDK provides the following functions for managing balance managers.

Click to open
createAndShareBalanceManager

Use createAndShareBalanceManager to create a new balance manager and automatically share it. The call returns a function that takes a Transaction object.

Click to open
createBalanceManagerWithOwner

Use createBalanceManagerWithOwner to create a new balance manager with a custom owner. Returns the manager object. The call returns a function that takes a Transaction object.

Parameters

  • ownerAddress: String representing the address of the owner.
Click to open
shareBalanceManager

Use shareBalanceManager to share a balance manager that you created but have not yet shared. The call returns a function that takes a Transaction object.

Parameters

  • manager: TransactionArgument representing the balance manager to share.

Deposit and withdraw functions​

Click to open
depositIntoManager

Use depositIntoManager to deposit funds into a balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • coinKey: String that identifies the coin to deposit.
  • amountToDeposit: Number representing the amount to deposit.
Click to open
withdrawFromManager

Use withdrawFromManager to withdraw funds from a balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • coinKey: String that identifies the coin to withdraw.
  • amountToWithdraw: Number representing the amount to withdraw.
  • recipient: String representing the recipient address.
Click to open
withdrawAllFromManager

Use withdrawAllFromManager to withdraw all funds of a specific coin type from a balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • coinKey: String that identifies the coin to withdraw.
  • recipient: String representing the recipient address.
Click to open
checkManagerBalance

Use checkManagerBalance to check the balance of a specific coin in a balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • coinKey: String that identifies the coin to check.

Trade proof functions​

Click to open
generateProof

Use generateProof to generate a trade proof for the balance manager. Automatically calls the appropriate function based on whether a tradeCap is set: either generateProofAsOwner or generateProofAsTrader, both described in this section. The call returns a function that takes a Transaction object. placeLimitOrder generates the trade proof itself from balanceManagerKey, so you don't need to call generateProof before placing an order.

Parameters

  • managerKey: String that identifies the balance manager.
Click to open
generateProofAsOwner

Use generateProofAsOwner to generate a trade proof as the owner of the balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerId: String representing the ID of the balance manager.
Click to open
generateProofAsTrader

Use generateProofAsTrader to generate a trade proof using a tradeCap. The call returns a function that takes a Transaction object.

Parameters

  • managerId: String representing the ID of the balance manager.
  • tradeCapId: String representing the ID of the trade cap.

Capability functions​

Click to open
mintTradeCap

Use mintTradeCap to mint a tradeCap for the balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
Click to open
mintDepositCap

Use mintDepositCap to mint a depositCap for the balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
Click to open
mintWithdrawalCap

Use mintWithdrawalCap to mint a withdrawCap for the balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
Click to open
depositWithCap

Use depositWithCap to deposit funds into a balance manager using a depositCap. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • coinKey: String that identifies the coin to deposit.
  • amountToDeposit: Number representing the amount to deposit.
Click to open
withdrawWithCap

Use withdrawWithCap to withdraw funds from a balance manager using a withdrawCap. The call returns a function that takes a Transaction object.

Unlike withdrawFromManager, withdrawWithCap takes no recipient. When you add the call to a transaction, the result is the withdrawn coin, which you transfer yourself, as in the Mint and use capabilities example.

Parameters

  • managerKey: String that identifies the balance manager.
  • coinKey: String that identifies the coin to withdraw.
  • amountToWithdraw: Number representing the amount to withdraw.
Click to open
revokeTradeCap

Use revokeTradeCap to revoke a TradeCap. This also revokes the associated DepositCap and WithdrawCap. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • tradeCapId: String representing the ID of the TradeCap to revoke.

Referral functions​

Click to open
setBalanceManagerReferral

Use setBalanceManagerReferral to set a pool-specific referral for the balance manager. Requires a tradeCap for permission checking. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • referral: String representing the ID of the pool referral (DeepBookPoolReferral). Pass the ID string, as in the Set and manage referrals example.
  • tradeCap: TransactionArgument representing the trade cap for permission.
Click to open
unsetBalanceManagerReferral

Use unsetBalanceManagerReferral to remove a referral from the balance manager for a specific pool. Requires a tradeCap for permission checking. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • poolKey: String that identifies the pool to unset the referral for.
  • tradeCap: TransactionArgument representing the trade cap for permission.
Click to open
getBalanceManagerReferralId

Use getBalanceManagerReferralId to get the referral ID associated with a balance manager for a specific pool. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
  • poolKey: String that identifies the pool.

Registry functions​

Click to open
registerBalanceManager

Use registerBalanceManager to register a balance manager with the registry. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.

Read-only functions​

Click to open
owner

Use owner to get the owner address of a balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
Click to open
id

Use id to get the ID of a balance manager. The call returns a function that takes a Transaction object.

Parameters

  • managerKey: String that identifies the balance manager.
Click to open
balanceManagerReferralOwner

Use balanceManagerReferralOwner to get the owner address of a pool referral (DeepBookPoolReferral). The call returns a function that takes a Transaction object.

Parameters

  • referralId: String representing the ID of the referral.
Click to open
balanceManagerReferralPoolId

Use balanceManagerReferralPoolId to get the pool ID associated with a pool referral (DeepBookPoolReferral). The call returns a function that takes a Transaction object.

Parameters

  • referralId: String representing the ID of the referral.

Examples​

The following examples demonstrate common balance manager operations.

How do I create and share a balance manager?​

// Example: Create and share a new balance manager
createBalanceManager = (tx: Transaction) => {
	tx.add(this.balanceManager.createAndShareBalanceManager());
};

Create a balance manager with custom owner​

// Example: Create a balance manager with custom owner and share it
createManagerWithOwner = (tx: Transaction) => {
	const ownerAddress = '0x123...';

	// Create the manager with custom owner
	const manager = tx.add(this.balanceManager.createBalanceManagerWithOwner(ownerAddress));

	// Share the manager
	tx.add(this.balanceManager.shareBalanceManager(manager));
};

How do I deposit and withdraw funds?​

// Example: Deposit USDC into a balance manager
depositFunds = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const coinKey = 'DBUSDC';
	const amount = 1000; // 1000 USDC

	tx.add(this.balanceManager.depositIntoManager(managerKey, coinKey, amount));
};

// Example: Withdraw SUI from a balance manager
withdrawFunds = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const coinKey = 'SUI';
	const amount = 100; // 100 SUI
	const recipient = '0x456...';

	tx.add(this.balanceManager.withdrawFromManager(managerKey, coinKey, amount, recipient));
};

// Example: Withdraw all DEEP from a balance manager
withdrawAllDeep = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const coinKey = 'DEEP';
	const recipient = '0x456...';

	tx.add(this.balanceManager.withdrawAllFromManager(managerKey, coinKey, recipient));
};

Mint and use capabilities​

// Example: Mint a TradeCap and use it
mintAndUseTradeCap = async (tx: Transaction) => {
	const managerKey = 'MANAGER_1';

	// Mint the TradeCap
	const tradeCap = tx.add(this.balanceManager.mintTradeCap(managerKey));

	// Transfer to a trader
	const traderAddress = '0x789...';
	tx.transferObjects([tradeCap], traderAddress);
};

// Example: Use DepositCap to deposit funds
depositWithCapability = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const coinKey = 'DBUSDC';
	const amount = 5000; // 5000 USDC

	tx.add(this.balanceManager.depositWithCap(managerKey, coinKey, amount));
};

// Example: Use WithdrawCap to withdraw funds
withdrawWithCapability = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const coinKey = 'SUI';
	const amount = 50; // 50 SUI

	const withdrawnCoin = tx.add(this.balanceManager.withdrawWithCap(managerKey, coinKey, amount));

	// Transfer the withdrawn coin
	tx.transferObjects([withdrawnCoin], '0xabc...');
};

How do I generate a trade proof?​

// Example: Generate a trade proof and use it to place an order
placeOrderWithProof = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const poolKey = 'SUI_DBUSDC';

	// Generate proof automatically (uses owner or tradeCap method)
	const proof = tx.add(this.balanceManager.generateProof(managerKey));

	// Use the proof to place an order
	tx.add(
		this.deepBook.placeLimitOrder({
			poolKey: poolKey,
			balanceManagerKey: managerKey,
			clientOrderId: '12345',
			price: 2.5,
			quantity: 100,
			isBid: true,
			payWithDeep: true,
		}),
	);
};

Set and manage referrals​

// Example: Set a pool-specific referral for a balance manager
setManagerReferral = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const referralId = '0xdef...'; // DeepBookPoolReferral ID

	// Get or create the TradeCap
	const tradeCap = tx.object('0x...'); // Assuming tradeCap is already minted

	tx.add(this.balanceManager.setBalanceManagerReferral(managerKey, referralId, tradeCap));
};

// Example: Unset a referral for a specific pool
unsetManagerReferral = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const poolKey = 'SUI_DBUSDC';
	const tradeCap = tx.object('0x...');

	tx.add(this.balanceManager.unsetBalanceManagerReferral(managerKey, poolKey, tradeCap));
};

Complete workflow​

// Example: Complete balance manager setup workflow
completeSetup = async (tx: Transaction) => {
	const ownerAddress = '0x123...';

	// Step 1: Create manager with custom owner
	const manager = tx.add(this.balanceManager.createBalanceManagerWithOwner(ownerAddress));

	// Step 2: Share the manager
	tx.add(this.balanceManager.shareBalanceManager(manager));

	// Step 3: Mint capabilities
	const tradeCap = tx.add(this.balanceManager.mintTradeCap('MANAGER_1'));
	const depositCap = tx.add(this.balanceManager.mintDepositCap('MANAGER_1'));
	const withdrawCap = tx.add(this.balanceManager.mintWithdrawalCap('MANAGER_1'));

	// Step 4: Transfer capabilities to owner
	tx.transferObjects([depositCap, withdrawCap, tradeCap], ownerAddress);
};

Trade proofs in order placement​

placeLimitOrder identifies the balance manager by balanceManagerKey and takes no trade proof parameter. You do not need to call generateProof and pass its result when you place an order. For example, the following function deposits into a balance manager and places an order in the same transaction:

	tx.add(client.deepbook.balanceManager.depositIntoManager(managerKey, depositCoinKey, depositAmount));
	tx.add(
		client.deepbook.deepBook.placeLimitOrder({
			poolKey,
			balanceManagerKey: managerKey,
			clientOrderId,
			price,
			quantity,
			isBid: false,
			orderType: OrderType.POST_ONLY,
		}),
	);