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.

createAndShareBalanceManager​

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

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.

createBalanceManagerWithOwnerAndCaps​

Use createBalanceManagerWithOwnerAndCaps to create a new balance manager with a custom owner and all three capabilities (deposit, withdraw, trade) in one call. Returns an object with manager, depositCap, withdrawCap, and tradeCap. The call returns a function that takes a Transaction object.

caution

The DeepBookV3 SDK uses depositCap, withdrawCap, and tradeCap, while Move code using DeepBookV3 uses DepositCap, WithdrawCap, and TradeCap.

Parameters

  • ownerAddress: String representing the address of the owner.

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​

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.

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.

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.

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​

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.

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.

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​

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.

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.

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.

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.

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.

Referral functions​

setReferral​

Use setReferral to set a 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.
  • tradeCap: TransactionArgument representing the trade cap for permission.

unsetReferral​

Use unsetReferral to remove a referral from 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.
  • tradeCap: TransactionArgument representing the trade cap for permission.

Registry functions​

registerManager​

Use registerManager 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​

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.

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.

referralOwner​

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

Parameters

  • referral_id: 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 and all capabilities​

// Example: Create a balance manager with custom owner and get all capabilities
createManagerWithCaps = (tx: Transaction) => {
	const ownerAddress = '0x123...';

	const { manager, depositCap, withdrawCap, tradeCap } = tx.add(
		this.balanceManager.createBalanceManagerWithOwnerAndCaps(ownerAddress),
	);

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

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

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 referral for a balance manager
setManagerReferral = (tx: Transaction) => {
	const managerKey = 'MANAGER_1';
	const referralId = '0xdef...';

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

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

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

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

Complete workflow​

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

	// Step 1: Create manager with all capabilities
	const { manager, depositCap, withdrawCap, tradeCap } = tx.add(
		this.balanceManager.createBalanceManagerWithOwnerAndCaps(ownerAddress),
	);

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

	// Step 3: Register with registry
	// Note: Need to wait for manager to be created and get its key
	// This would typically be done in a subsequent transaction

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

The DeepBookV3 SDK repository on GitHub.

•
DeepBookV3 SDK node package

The DeepBookV3 SDK node package on NPM.

•
DeepBookV3 repository

The DeepBookV3 repository on GitHub.