Connect SDK

Connect GearboxSDK to the networks your application uses. Reuse the connected instance to find strategies, prepare transactions, and read positions.

Install

npm install @gearbox-protocol/sdk viem

Configure and connect

Create gearbox.ts. Set the chain ID and its RPC URL, then connect:

import { GearboxSDK } from "@gearbox-protocol/sdk";
import { getNetworkType } from "@gearbox-protocol/sdk/onchain";

const chainId = 1; // Ethereum mainnet
const rpcUrl = "https://your-rpc.example"; // Replace with your RPC URL for the selected network
const mode = "both";
const apiBaseUrl = "https://api.gearbox.fi";

const network = getNetworkType(chainId);

export const sdk = new GearboxSDK({
  mode,
  networks: [network],
  onchain: { chains: { [network]: { rpcURLs: [rpcUrl] } } },
  offchain: { baseUrl: apiBaseUrl },
});

await sdk.attach();

This configuration connects to your RPC endpoint and the Gearbox API, providing protocol data, analytics, and transaction preparation through one SDK instance. await sdk.attach() loads the markets, contracts, and protocol state needed by subsequent calls. Wait for it once during startup, then reuse sdk.

High-level reads, preparation, and preview calls automatically attempt to refresh onchain state when it is older than 30 seconds by default. Refresh happens when a call needs it, not on a background timer; manual refresh is normally unnecessary. If synchronization fails, the SDK can continue using the previous snapshot, so check the returned block and timestamp. Direct access to low-level cached prices or market configuration does not trigger this freshness check.

This connects the SDK to blockchain data. Supply the owner's address directly when reading leveraged positions or preparing transactions; no wallet connection or signer is required for these steps. Signing and execution are handled by your chosen execution system.

Network names

getNetworkType(chainId) resolves the SDK's network name automatically and throws for unsupported chain IDs. The SDK uses these mappings:

Continue with Open, Monitor, or Manage.