SDK Setup

Connect the Gearbox SDK once when your TypeScript process starts, then reuse the attached instance for pool, account, and liquidation operations.

Install

npm install @gearbox-protocol/sdk viem dotenv

Preview SDK

Some integration guides use APIs that are available in the SDK next release channel but have not reached the stable release. Pages that require it are marked Preview SDK.

To test those integrations now, install:

npm install @gearbox-protocol/sdk@next viem dotenv

Use the stable package unless a guide specifically requires the preview SDK. The preview requirement will be removed when the APIs reach the stable release.

Configure

For local development, create a file named .env in the project root:

DOTENV

GEARBOX_NETWORK=Mainnet
RPC_URL=https://your-rpc.example

The dotenv package loads these values into process.env. Do not commit .env. In production, provide the same variables through your deployment platform or secret manager.

Attach

Create a shared module such as gearbox.ts:

TypeScript

import "dotenv/config";
import { NetworkType, OnchainSDK } from "@gearbox-protocol/sdk";

const rpcUrl = process.env.RPC_URL!;
const network = NetworkType.parse(
  process.env.GEARBOX_NETWORK ?? "Mainnet",
);

export const sdk = new OnchainSDK(network, {
  rpcURLs: [rpcUrl],
  timeout: 30_000,
  retryCount: 2,
});

await sdk.attach();

attach() discovers the Gearbox markets and contracts for the selected network. Wait for it to complete before calling SDK features, and reuse the resulting sdk instance instead of attaching again for each operation.

SDK-based integration guides assume this step is complete and import the shared instance:

TypeScript

import { sdk } from "./gearbox";

Source

Gearbox SDK