# Connect SDK

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

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

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

## Install

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

## Configure and connect

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

```typescript
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:

| Chain ID | Network name |
| --- | --- |
| 1 | `Mainnet` |
| 42161 | `Arbitrum` |
| 10 | `Optimism` |
| 8453 | `Base` |
| 146 | `Sonic` |
| 4326 | `MegaETH` |
| 143 | `Monad` |
| 80094 | `Berachain` |
| 43114 | `Avalanche` |
| 56 | `BNB` |
| 480 | `WorldChain` |
| 42793 | `Etherlink` |
| 43111 | `Hemi` |
| 1135 | `Lisk` |
| 9745 | `Plasma` |
| 5031 | `Somnia` |

Continue with [Open](https://docs.gearbox.finance/developers/open-leveraged-position),
[Monitor](https://docs.gearbox.finance/developers/monitor-position), or [Manage](https://docs.gearbox.finance/developers/manage-position).