# Margin Pool SDK

*[Documentation index](/llms.txt) · [Full index](/llms-full.txt)*

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 that can be used to supply and withdraw from margin pools. One `SupplierCap` can be used across multiple margin pools. The call returns a function that takes a `Transaction` object.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

### `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.
- `supplierCap`: `TransactionObjectArgument` representing the supplier cap.
- `amountToDeposit`: Number representing the amount to supply.
- `referralId`: Optional string representing the referral ID.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

### `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.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

### `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.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

### `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.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

## Read-only functions

The following functions query margin pool state without modifying it.

### Pool information

Query basic pool information and configuration.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

### Supply and borrow metrics

Query current supply and borrow amounts and shares.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

### Interest rate

Query the current interest rate based on utilization.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

### User positions

Query a supplier's position in the pool.

<!-- External code reference: packages/deepbook-v3/src/transactions/marginPool.ts -->

## Examples

The following examples demonstrate common margin pool operations.

### Create a supplier cap

```tsx
/**
 * @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));
};
```

### Supply liquidity

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

	tx.add(
		this.marginPoolContract.supplyToMarginPool(
			coinKey,
			supplierCap,
			amountToSupply,
			// Optional: provide referral ID
		),
	);
};
```

### Supply with referral

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

### Withdraw liquidity

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

### Create and manage referrals

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

### Query pool state

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