> For the complete documentation index, see [llms.txt](https://surf-2.gitbook.io/surfliquid-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://surf-2.gitbook.io/surfliquid-docs/sdk-docs/core-sdk-reference.md).

# Core SDK Reference

The core SDK (`@surf_liquid/core-sdk`) provides full programmatic access to Surf's savings infrastructure. It is framework-agnostic and works in React, Vue, Svelte or Node.js.

**Package:** `@surf_liquid/core-sdk`\
**Language:** TypeScript (ships ESM, CJS and type definitions)\
**Peer dependency:** ethers v6\
**Licence:** MIT

***

### SurfClient

The entry point for all SDK operations.

```typescript
import { SurfClient } from '@surf_liquid/core-sdk';

const client = new SurfClient({
  provider: window.ethereum,       // any EIP-1193 wallet provider
  walletAddress: '0xUserAddress',
  chainId: 8453,                   // Base mainnet (1 = Ethereum, 137 = Polygon)
  appId: 'YOUR_APP_ID',
  autoApprove: true,               // automatic ERC-20 approvals
});
```

***

### Wallet Connection

The SDK works with any EIP-1193 compatible wallet provider:

* MetaMask
* WalletConnect
* Coinbase Wallet
* Safe (Gnosis) multi-sig
* Rabby
* Phantom
* Trust Wallet
* Any browser-injected wallet

***

### Authentication

Users authenticate with a wallet signature (SIWE-style). Sessions are cookie-based (httpOnly, secure, cross-origin). Your application never needs to store or manage authentication tokens.

***

### Vault Operations

**Deploy a vault**\
On a user's first deposit, a dedicated smart contract vault is deployed on-chain in a single call. Each user gets their own vault. Funds are never co-mingled.

**Deposit**\
Deposit supported assets into the user's vault. The SDK handles ERC-20 approvals and native ETH wrapping automatically when `autoApprove` is enabled.

**Withdraw**\
Withdraw any amount at any time. Partial and full withdrawals are supported. Accrued returns are included automatically.

**Automatic management**\
Once funds are deposited, Surf AI routes them to the best available opportunity across approved venues. Rebalancing and cross-chain movements are handled automatically by the platform.

***

### Analytics

The SDK provides rich, per-user analytics for building dashboards and user-facing statements:

* **Portfolio value and deposits** - total value, principal deposited and per-asset balances in USD
* **APY** - blended current APY with breakdown by source (native, Merkl, league) plus trailing 7, 14 and 30-day windowed APY
* **Earnings and profit** - total and per-asset earnings, profit amount and profit percentage
* **League standing** - rank, XP and estimated rewards in SurfLeagues
* **Activity feed** - complete, structured history of deposits, withdrawals, rebalances, cross-chain moves, migrations and reward claims. Supports date-range filtering. Each event includes amount, token, source and destination vault, and APY before and after.

***

### Asset and APY Discovery

List supported assets per chain with live APY data. This endpoint requires no wallet connection or user login, making it ideal for displaying available savings options before the user connects their wallet.

***

### TypeScript Support

All types are exported from the package root:

```typescript
import type {
  SurfWidgetProps, SurfTheme, SurfConfig,
  VaultInfo, VaultActivity, AgentMessage,
  SurfSupportedAsset, ISurfClient,
  DepositStep, WithdrawStep,
} from '@surf_liquid/core-sdk';
```

***

### Utility Functions

```typescript
import { fromWei, toWei } from '@surf_liquid/core-sdk';

fromWei(1420000n, 6)   // "1.42"   (on-chain bigint to human-readable)
toWei("1.42", 6)       // "1420000" (human-readable to on-chain string)
```

***

### Output Formats

| Format                  | File                |
| ----------------------- | ------------------- |
| ES Module               | `dist/index.esm.js` |
| CommonJS                | `dist/index.js`     |
| TypeScript Declarations | `dist/index.d.ts`   |
| Scoped Styles           | `dist/index.css`    |