Skip to main content

Margin Pool SDK

Supplying liquidity to margin pools enables lenders to earn interest on their assets while providing borrowing capacity for margin traders. The Margin Pool SDK provides functions for managing liquidity positions and earning referral fees.

Margin pool functions​

The DeepBook Margin SDK provides the following functions for interacting with margin pools.

mintSupplierCap​

Use mintSupplierCap to create a new supplier capability (SupplierCap). Both supplyToMarginPool and withdrawFromMarginPool require a SupplierCap, so mint one before you supply. You can use one SupplierCap across multiple margin pools. The call returns a function that takes a Transaction object. Pass that function to tx.add, which returns the new SupplierCap, as shown in How do I create a supplier cap?.

supplyToMarginPool​

Use supplyToMarginPool to supply assets to a margin pool and earn interest. You can optionally provide a referral ID to share fees with the referrer. The call returns a function that takes a Transaction object.

Parameters

  • coinKey: String that identifies the asset type, for example 'USDC'.
  • supplierCap: TransactionObjectArgument representing the supplier cap.
  • amountToDeposit: Number representing the amount to supply.
  • referralId: Optional string representing the referral ID, the object ID of a referral created with mintSupplyReferral.

withdrawFromMarginPool​

Use withdrawFromMarginPool to withdraw supplied assets from a margin pool. If no amount is specified, it withdraws all available shares. The call returns a function that takes a Transaction object.

Parameters

  • coinKey: String that identifies the asset type.
  • supplierCap: TransactionObjectArgument representing the supplier cap.
  • amountToWithdraw: Optional number representing the amount to withdraw.

mintSupplyReferral​

Use mintSupplyReferral to create a supply referral for earning fees. The call returns a function that takes a Transaction object.

Parameters

  • coinKey: String that identifies the asset type.

withdrawReferralFees​

Use withdrawReferralFees to withdraw accumulated referral fees. The call returns a function that takes a Transaction object.

Parameters

  • coinKey: String that identifies the asset type.
  • referralId: String representing the referral ID.

Read-only functions​

The following functions query margin pool state without modifying it.

Pool information​

Query basic pool information and configuration.

Supply and borrow metrics​

Query current supply and borrow amounts and shares. totalSupply and totalBorrow take a coinKey string, as shown in How do I query pool state?.

Interest rate​

Query the current interest rate based on utilization. interestRate takes a coinKey string, as shown in How do I query pool state?.

User positions​

Query a supplier's position in the pool. userSupplyShares and userSupplyAmount take a coinKey string and the object ID of your supplier cap, as shown in How do I query pool state?.

Examples​

The following examples demonstrate common margin pool operations. The examples use class member syntax and assume the class already sets this.marginPoolContract and this.config.address. Replace each '0x...' placeholder with the object ID of the SupplierCap you create with mintSupplierCap or the referral you create with mintSupplyReferral.

To supply and withdraw liquidity:

  1. Mint a SupplierCap with mintSupplierCap and transfer it to your address.
  2. Supply assets with supplyToMarginPool, passing the SupplierCap.
  3. Withdraw assets with withdrawFromMarginPool, passing the same SupplierCap.

How do I create a supplier cap?​

The first statement in the following example shows only the mintSupplierCap signature with an empty body, not the SDK implementation. The example usage passes the returned function to tx.add and transfers the resulting SupplierCap to this.config.address.

/**
 * @description Mint a supplier cap for margin pool
 * @returns A function that takes a Transaction object
 */
mintSupplierCap = () => (tx: Transaction) => {};

// Example usage
createSupplierCap = (tx: Transaction) => {
	const supplierCap = tx.add(this.marginPoolContract.mintSupplierCap());
	// Transfer to user or store for later use
	tx.transferObjects([supplierCap], tx.pure.address(this.config.address));
};

How do I supply liquidity to a margin pool?​

// Example: Supply 1000 USDC to the margin pool
supplyLiquidity = (tx: Transaction) => {
	const coinKey = 'USDC';
	const supplierCapId = '0x...'; // ID of your supplier cap, created with mintSupplierCap
	const supplierCap = tx.object(supplierCapId);
	const amountToSupply = 1000;

	tx.add(
		this.marginPoolContract.supplyToMarginPool(
			coinKey,
			supplierCap,
			amountToSupply,
			// Optional: provide referral ID to share fees with the referrer
		),
	);
};

How do I supply with a referral?​

// Example: Supply 1000 USDC with a referral
supplyWithReferral = (tx: Transaction) => {
	const coinKey = 'USDC';
	const supplierCapId = '0x...';
	const supplierCap = tx.object(supplierCapId);
	const referralId = '0x...'; // Referral object ID

	tx.add(
		this.marginPoolContract.supplyToMarginPool(
			coinKey,
			supplierCap,
			1000,
			referralId, // Referral will earn fees
		),
	);
};

How do I withdraw from a margin pool?​

// Example: Withdraw 500 USDC from the margin pool
withdrawLiquidity = (tx: Transaction) => {
	const coinKey = 'USDC';
	const supplierCapId = '0x...';
	const supplierCap = tx.object(supplierCapId);

	tx.add(this.marginPoolContract.withdrawFromMarginPool(coinKey, supplierCap, 500));
};

// Example: Withdraw all available liquidity
withdrawAll = (tx: Transaction) => {
	const coinKey = 'USDC';
	const supplierCapId = '0x...';
	const supplierCap = tx.object(supplierCapId);

	// No amount specified = withdraw all
	tx.add(this.marginPoolContract.withdrawFromMarginPool(coinKey, supplierCap));
};

How do I create referrals and claim referral fees?​

// Example: Create a supply referral
createReferral = (tx: Transaction) => {
	const coinKey = 'USDC';
	tx.add(this.marginPoolContract.mintSupplyReferral(coinKey));
};

// Example: Withdraw referral fees
claimReferralFees = (tx: Transaction) => {
	const coinKey = 'USDC';
	const referralId = '0x...'; // Your referral object ID
	tx.add(this.marginPoolContract.withdrawReferralFees(coinKey, referralId));
};

How do I query pool state?​

// Example: Check interest rate and utilization
checkPoolMetrics = async (tx: Transaction) => {
	const coinKey = 'USDC';

	// Get total supply and borrow
	const totalSupply = tx.add(this.marginPoolContract.totalSupply(coinKey));
	const totalBorrow = tx.add(this.marginPoolContract.totalBorrow(coinKey));

	// Get current interest rate
	const interestRate = tx.add(this.marginPoolContract.interestRate(coinKey));

	// Query user position
	const supplierCapId = '0x...';
	const userShares = tx.add(this.marginPoolContract.userSupplyShares(coinKey, supplierCapId));
	const userAmount = tx.add(this.marginPoolContract.userSupplyAmount(coinKey, supplierCapId));
};