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.

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 was created but 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. The call returns a function that takes a Transaction object.

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.

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 referral ID (DeepBookPoolReferral).
  • 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.

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));
};

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...');
};

Generate trade proofs​

// 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);
};