# Pool Integration

> Markdown export of the Gearbox Protocol documentation page for agents and retrieval systems.

Canonical page: https://docs.gearbox.finance/developers/pool-integration
Source file: content/developers/pool-integration.mdx
Section router: https://docs.gearbox.finance/developers/llms.txt
Section full export: https://docs.gearbox.finance/developers/llms-full.txt

Use the Gearbox SDK to resolve a pool, build unsigned deposit and withdrawal
transactions, and preview the token amounts. The same flow works for every
pool underlying.

Before continuing, [install and attach the Gearbox SDK](https://docs.gearbox.finance/developers/sdk-setup).
The examples use these inputs:

| Variable | Type | Meaning |
|---|---|---|
| `sdk` | `OnchainSDK` | Attached Gearbox SDK instance |
| `poolAddress` | `Address` | Gearbox pool to integrate |
| `lender` | `Address` | Wallet supplying the underlying and owning the pool shares |
| `depositAmount` | `bigint` | Underlying amount to deposit, in native token units |
| `sharesToRedeem` | `bigint` | Pool-share amount to redeem, in native token units |

## Resolve the pool

Resolve the market once from the configured pool address:

```typescript
import { RWA_UNDERLYING_DEFAULT } from "@gearbox-protocol/sdk";

const market = sdk.marketRegister.findByPool(poolAddress);
const pool = market.pool.pool;
const underlying = market.underlying;
const underlyingMeta = sdk.tokensMeta.mustGet(underlying);

const requiresRwaUnderlying =
  sdk.tokensMeta.isRWAUnderlying(underlyingMeta) &&
  underlyingMeta.contractType === RWA_UNDERLYING_DEFAULT;

if (pool.isPaused) throw new Error("Pool is paused");
```

`underlying` is the ERC-20 supplied to and returned by this pool. `pool.address`
is also the pool-share token address.

> **If `requiresRwaUnderlying` is `true`:** the pool accepts
> `DefaultRWAUnderlying`, not the ERC-20 asset wrapped by it. Follow
> [Obtaining RWA Underlying](https://docs.gearbox.finance/developers/obtain-rwa-underlying) to obtain
> the token, then return to the deposit flow below.

## Deposit

This step assumes the lender already holds the exact `underlying` resolved
above.

### Preview deposit

```typescript
const expectedShares = await pool.contract.read.previewDeposit([
  depositAmount,
]);
```

`expectedShares` is the expected pool-share output for `depositAmount`.

### Generate deposit transaction

```typescript
const depositTransaction = pool.depositWithReferral(
  depositAmount,
  lender,
  0n,
);
```

Approve `underlying` for `pool.address` with an allowance of at least
`depositAmount`. `depositTransaction` is the unsigned deposit call.

## Check how much can be withdrawn

Read the ERC-4626 limits through the SDK client:

```typescript
const [withdrawableUnderlying, redeemableShares] = await Promise.all([
  pool.contract.read.maxWithdraw([lender]),
  pool.contract.read.maxRedeem([lender]),
]);
```

`withdrawableUnderlying` is the current asset-denominated limit.
`redeemableShares` is the current share-denominated limit. Both account for the
lender's position, available pool liquidity, withdrawal fees, and pause state.

## Withdraw

The SDK withdrawal builder redeems pool shares.

### Preview withdrawal

```typescript
const expectedUnderlying = await pool.contract.read.previewRedeem([
  sharesToRedeem,
]);
```

`expectedUnderlying` is the expected underlying output after the withdrawal
fee.

### Generate withdrawal transaction

```typescript
const withdrawalTransaction = pool.redeem(
  sharesToRedeem,
  lender,
  lender,
);
```

No pool-share approval is required when `lender` submits this transaction. If
another address submits it, `lender` must approve that address to spend the
shares. `withdrawalTransaction` is the unsigned redemption call.

## Pricing

Use the ERC-4626 conversion methods for the current accounting rate:

```typescript
const oneTokenUnit = 10n ** BigInt(pool.decimals);

const [underlyingPerShare, sharesPerUnderlying] = await Promise.all([
  pool.contract.read.convertToAssets([oneTokenUnit]),
  pool.contract.read.convertToShares([oneTokenUnit]),
]);
```

Conversions exclude operation-specific fees. Use `previewDeposit` and
`previewRedeem` when preparing an actual transaction.

## Integration boundary

This page provides Gearbox address resolution, current limits, previews, exact
approval targets, and unsigned calldata. The lender's existing infrastructure
owns allowance state, simulation, signing, submission, and monitoring.

## Sources

- [Gearbox SDK pool transaction builders](https://github.com/Gearbox-protocol/sdk/blob/next/src/sdk/market/pool/PoolV310Contract.ts#L150-L181)
- [Gearbox pool ERC-4626 implementation](https://github.com/Gearbox-protocol/core-v3/blob/next/contracts/pool/PoolV3.sol)