> For the complete documentation index, see [llms.txt](https://docs.kpk.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kpk.io/vaults/vault-integration/integration/gearbox.md).

# Gearbox

How to integrate KPK Gearbox Earn Pools, with depositWithReferral and KPK referral code 4143, ERC-4626 withdrawals, Gearbox TypeScript SDK reads, and Merkl reward claims.

This page covers the Gearbox-specific integration flows for KPK Earn Pools: direct ERC-4626 calls with the KPK referral code, the Gearbox TypeScript SDK, and supporting reference material. For the general integrator overview and audience-routing, start at the [Integration page](/vaults/vault-integration/integration.md).

End-users who simply want to deposit should use the [Gearbox UI](https://kpk.gearbox.finance/) directly. Pool addresses, supported assets, and current parameters are listed on each [pool page](/vaults/vaults/gearbox.md).

{% hint style="info" %}
The guide uses wstETH and the `kpkwstETH` Earn Pool as the example.
{% endhint %}

### Integration paths

KPK pools on Gearbox are **ERC-4626 passive lending pools**. Unlike Morpho, Gearbox pools do not allocate across multiple underlying markets: the pool lends a single asset to Gearbox borrowers through the Credit Account system, and the integrator-facing surface is the pool itself.

Two integration paths:

* **Direct ERC-4626 calls** with `depositWithReferral`. Simple, two transactions, and ensures KPK is correctly attributed via the referral code (`4143`). This is the recommended path for most integrators.
* **Gearbox TypeScript SDK.** Higher-level access to pool data, market discovery, and transaction construction. Useful if you also need market metadata (supply rate, total assets, available liquidity) or plan to support multiple Gearbox pools.

For pool discovery, KPK-curated Earn Pools are listed on the [pool directory](/vaults/vaults/gearbox.md) and can also be retrieved onchain via the Gearbox Market Configurator.

### Direct ERC-4626 integration

The recommended deposit path is `depositWithReferral`, which is the standard ERC-4626 `deposit` plus a referral code that attributes the deposit to KPK.

#### Deposit

{% stepper %}
{% step %}
**Approve the pool to spend wstETH.**

Call [`approve(address, uint256)`](https://etherscan.io/address/0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0#writeProxyContract#F1) on wstETH (`0x7f39C581F595B53c5cb19bD0b3f8dA6c935E2Ca0`):

* `spender(address)` = `0xa9d17f6d3285208280a1fd9b94479c62e0aaba64`, i.e. [`kpkwstETH`](/vaults/vaults/gearbox/ethereum/wsteth.md)
* `value(amount)` = token amount to deposit
  {% endstep %}

{% step %}
**Deposit with the KPK referral code.**

Call [`depositWithReferral(uint256, address, uint256)`](https://etherscan.io/address/0xA9d17f6D3285208280a1Fd9B94479c62e0AABa64#writeContract#F4) on [`kpkwstETH`](/vaults/vaults/gearbox/ethereum/wsteth.md):

* `assets(uint256)` = tokens to be deposited
* `receiver(address)` = your address, or the address to which you want the receipt tokens sent
* `referralCode(uint256)` = `4143`, i.e. the KPK referral code
  {% endstep %}
  {% endstepper %}

The plain `deposit(assets, receiver)` ERC-4626 method also works if you cannot pass a referral code, but `depositWithReferral` is preferred so KPK is correctly attributed in Gearbox analytics.

#### Withdraw

{% stepper %}
{% step %}
**Withdraw a specific asset amount.**

Call [`withdraw(uint256, address, address)`](https://etherscan.io/address/0xA9d17f6D3285208280a1Fd9B94479c62e0AABa64#writeContract#F23) on [`kpkwstETH`](/vaults/vaults/gearbox/ethereum/wsteth.md):

* `assets(uint256)` = amount of wstETH to withdraw
* `receiver(address)` = the address that should receive the wstETH (or WETH, depending on configuration)
* `owner(address)` = the address whose shares should be burned (the depositor, or any address that has approved the caller)
  {% endstep %}
  {% endstepper %}

Or by share amount:

{% stepper %}
{% step %}
**Redeem a specific share amount.**

Call `redeem(shares, receiver, owner)` on the pool.
{% endstep %}
{% endstepper %}

### TypeScript SDK integration

The [`@gearbox-protocol/sdk`](https://docs.gearbox.finance/dev/sdk-guide-typescript/setup) package exposes pool state and transaction helpers. It is the right choice if your integration needs to read live pool metrics (supply rate, total assets, available liquidity) or supports multiple Gearbox pools at once.

#### Install and instantiate

```bash
npm install @gearbox-protocol/sdk viem
```

```typescript
import { GearboxSDK } from '@gearbox-protocol/sdk';
import { createPublicClient, http } from 'viem';
import { mainnet } from 'viem/chains';

const client = createPublicClient({ chain: mainnet, transport: http() });

const sdk = await GearboxSDK.attach({
  client,
  marketConfigurators: [], // empty array auto-discovers all markets
});
```

#### Read pool state

Find a KPK Earn Pool by its address and read its key metrics:

```typescript
const market = sdk.marketRegister.findByPool(
  '0xa9d17f6d3285208280a1fd9b94479c62e0aaba64', // kpkwstETH
);
const pool = market.pool;

// Supply APY (RAY-scaled supplyRate, converted to a percentage)
const RAY = 10n ** 27n;
const supplyAPY = Number((pool.supplyRate * 10000n) / RAY) / 100;

console.log(`Supply APY: ${supplyAPY}%`);
console.log(`Total assets: ${pool.totalAssets}`);
console.log(`Available liquidity: ${pool.availableLiquidity}`);
```

For deposits and withdrawals, the SDK currently focuses on Credit Account flows for borrowers. For passive lending into a KPK Earn Pool, use the direct ERC-4626 calls described above with the referral code; the SDK is most useful for the surrounding read-side state.

### Claim rewards

KPK Earn Pools may distribute additional GEAR or other incentive tokens via Merkl. Claim them with:

* Call [`claim(users, tokens, amounts, proofs)`](https://etherscan.io/address/0x3Ef3D8bA38EBe18DB133cEc108f4D14CE00Dd9Ae#writeProxyContract#F1) on the Merkl distributor, with the values returned by the [Merkl API](https://docs.merkl.xyz/) for the depositor's address.

The claim is a separate transaction and does not modify the user's deposited position.

### Reference

* **Gearbox developer docs:** [docs.gearbox.finance/dev](https://docs.gearbox.finance/dev).
* **TypeScript SDK setup:** [docs.gearbox.finance](https://docs.gearbox.finance/dev/sdk-guide-typescript/setup).
* **TypeScript SDK reading data:** [docs.gearbox.finance](https://docs.gearbox.finance/dev/sdk-guide-typescript/reading-data).
* **Merkl distributor API:** [docs.merkl.xyz](https://docs.merkl.xyz/).

### Support

For integration questions, technical reviews, or hands-on help, reach out to <sales@karpatkey.com> or use the [contact form](https://kpk.io/contact). For protocol-level Gearbox documentation, see [docs.gearbox.finance](https://docs.gearbox.finance/).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.kpk.io/vaults/vault-integration/integration/gearbox.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.