> ## Documentation Index
> Fetch the complete documentation index at: https://docs.soo.network/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Reference

# Simpfor.fun SDK Reference

Complete TypeScript SDK for the Simpfor.fun copy trading platform. Build copy trading apps, integrate trader analytics, and manage user wallets with ease.

## Quick Start

**Install**

```bash theme={"system"}
npm install simpfor-fun-sdk
```

**Basic Usage**

```typescript theme={"system"}
import { SimpforFunSDK } from 'simpfor-fun-sdk';

const sdk = new SimpforFunSDK();

// Authenticate
await sdk.sendVerificationCode('user@example.com');
const result = await sdk.verifyOtp('user@example.com', '123456');

// Get top traders
const traders = await sdk.fetchTopTraders();

// Start copy trading
const copyTrade = await sdk.createCopyTrade(
  result.data.user.uid,
  'trader-address',
  'your-wallet-address'
);
```

## Authentication

### Email Authentication (Recommended)

**Send Verification Code**

```typescript theme={"system"}
await sdk.sendVerificationCode(email: string)
```

**Verify OTP**

```typescript theme={"system"}
const result = await sdk.verifyOtp(email: string, code: string)
// Returns: { data: { user: User } }
```

### Social Authentication

**Privy Integration**

```typescript theme={"system"}
await sdk.privyLogin({
  privyAuthToken: string,
  privyEmail: string,
  referralCode?: string
})
```

**Google OAuth**

```typescript theme={"system"}
// Get auth URL
const { url } = await sdk.googleLogin({ referralCode?: string })

// Handle callback
await sdk.googleCallback(code: string, state: string)
```

## Copy Trading

### Core Operations

**Create Copy Trade**

```typescript theme={"system"}
await sdk.createCopyTrade(
  userId: number,
  leaderAddress: string,
  followerAddress: string
)
// Returns: { data: { info: CopyTradeInfo } }
```

**Start/Stop Copying**

```typescript theme={"system"}
// Start copying trades
await sdk.runCopyTrade(userId: number, copyTradeId: number)

// Stop copying (with optional position close)
await sdk.stopCopyTrade(
  userId: number, 
  copyTradeId: number, 
  closePositions: boolean
)

// Remove copy trade entirely
await sdk.removeCopyTrade(userId: number, copyTradeId: number)
```

**List Copy Trades**

```typescript theme={"system"}
const result = await sdk.listCopyTrades(userId: number)
// Returns: { data: { infos: CopyTradeInfo[] } }
```

### Performance Tracking

**Get PnL History**

```typescript theme={"system"}
await sdk.getCopyTradeHistoryPnl(
  userId: number,
  walletAddress: string,
  sortByPnlDesc: boolean,
  pagination: { page: number, limit: number }
)
```

**Get Trade Details**

```typescript theme={"system"}
await sdk.getCopyTradeDetails(
  userId: number,
  copyTradeId: number,
  pagination: { page: number, limit: number }
)
```

**Get Total PnL**

```typescript theme={"system"}
await sdk.getCopyTradeTotalPnl(userId: number, walletAddress: string)
// Returns: { data: { pnl: number } }
```

## Trader Discovery

### Top Traders

**Fetch All Top Traders**

```typescript theme={"system"}
const traders = await sdk.fetchTopTraders()
// Returns: Trader[]
```

**Paginated Top Traders**

```typescript theme={"system"}
await sdk.topTradersWithPeriod(
  sort: { field: string, order: 'asc' | 'desc' },
  pagination: { page: number, limit: number }
)
```

**Smart Categories**

```typescript theme={"system"}
const categories = await sdk.smartTraders()
// Returns: {
//   topValueTrader: TraderInfo[],
//   topRoiTrader: TraderInfo[],
//   topPnlTrader: TraderInfo[],
//   topFollowValueTrader: TraderInfo[]
// }
```

### Trader Analytics

**Trader Snapshot**

```typescript theme={"system"}
await sdk.traderSnapshot(
  address: string, 
  period: '7d' | '30d' | '90d' | '180d'
)
// Returns comprehensive performance data
```

**Trader Overview**

```typescript theme={"system"}
await sdk.traderOverview(address: string)
// Returns basic trader stats
```

**Share Information**

```typescript theme={"system"}
await sdk.shareInfo(address: string, period: string)
// Returns formatted data for social sharing
```

## Wallet Management

### KMS Wallet Operations

**Check Wallet Availability**

```typescript theme={"system"}
await sdk.checkWallet(address: string)
// Returns: { isAvailable: boolean, message?: string, errorCode?: string }
```

**Create KMS Key**

```typescript theme={"system"}
await sdk.createKmsKey(address: string)
// Returns: { agentKmsAddress: string, kmsExpireTimestamp: number }
```

**Activate KMS Wallet**

```typescript theme={"system"}
await sdk.activateKmsWallet(
  walletAddress: string,
  agentAddress: string,
  walletName: string,
  signRawAction: object,
  signature: string
)
```

**List User Wallets**

```typescript theme={"system"}
const wallets = await sdk.walletList()
// Returns: { keys: KeyEntry[] }
```

**Refresh Agent Wallet**

```typescript theme={"system"}
await sdk.refreshAgentWallet(address: string)
// Returns new expiry timestamp
```

### Builder Fee Management

**Get Builder Fee Info**

```typescript theme={"system"}
const feeInfo = await sdk.getBuilderFee()
// Returns: { builderAddress: string, builderFeeRate: string }
```

**Bind Builder**

```typescript theme={"system"}
await sdk.bindBuilder(
  walletAddress: string,
  approveRequest: ApproveBuilderFeeRequest,
  signature: string
)
```

## Cross-Chain Deposits

### Bridge Operations

**Get/Create Bridge Address**

```typescript theme={"system"}
await sdk.getBridgeAddress(userId: number, walletAddress: string)
// Returns: { userBridgeAddress: string }
```

**List Bridge Addresses**

```typescript theme={"system"}
await sdk.listBridgeAddress(userId: number)
// Returns: { addresses: BridgeAddress[] }
```

**Register Bridge with Permit**

```typescript theme={"system"}
await sdk.registerBridgeAddress(
  userId: number,
  permitRequest: PermitRequest
)
```

## User Management

### Watchlist

**Manage Watched Traders**

```typescript theme={"system"}
// Add to watchlist
await sdk.addWatchedTrader(address: string)

// Get watched traders
await sdk.getWatchedTraders(
  sort: { field: string, order: string },
  pagination: { page: number, limit: number }
)

// Remove from watchlist
await sdk.removeWatchedTrader(address: string)
```

### Referrals

**Get Referral Info**

```typescript theme={"system"}
await sdk.getReferralInfo()
// Returns referral stats and commissions
```

**Get Referral List**

```typescript theme={"system"}
await sdk.getReferralList(
  filterId?: string,
  startTime?: string,
  endTime?: string,
  pagination: { page: number, limit: number }
)
```

**Claim Commission**

```typescript theme={"system"}
await sdk.claimCommission(walletAddress: string)
```

### Coupons & Rewards

**Get User Coupons**

```typescript theme={"system"}
await sdk.userCoupons(status: 'active' | 'used' | 'expired')
```

**Claim Coupon**

```typescript theme={"system"}
await sdk.claimCoupon(couponId: string, walletAddress: string)
```

### Solana Integration

**Get Solana Address Status**

```typescript theme={"system"}
await sdk.getSolanaAddresses()
// Returns: { address: string, linked: boolean }
```

**Link Solana Address**

```typescript theme={"system"}
// Get auth message
const authMsg = await sdk.getSolanaAuthMessage(address: string)

// Link address (after user signs message)
await sdk.linkSolanaAddress(
  address: string,
  message: string,
  signature: string
)
```

## TypeScript Types

### Core Interfaces

```typescript theme={"system"}
interface User {
  uid: number;
  email: string;
  referralCode: string;
  invitedByCode: string;
}

interface Trader {
  address: string;
  value: number;
  roi: number;
  pnl: number;
  apy: number;
  maxDrawdown: number;
  sharpeRatio: number;
  winRate: number;
  tradingVolume: number;
  followValue: number;
  watched: boolean;
  copying: boolean;
}

interface CopyTradeInfo {
  copyTradeId: number;
  active: boolean;
  description: string;
  followerAccount: string;
  leaderAccount: string;
  watched: boolean;
  createTime: string;
  updateTime: string;
}

interface ApiResponse<T> {
  code: number;
  message: string;
  data: T;
}
```

### Request Types

```typescript theme={"system"}
interface CreateCopyTradeReq {
  userId: number;
  leaderAccount: string;
  followerAccount: string;
}

interface ApproveBuilderFeeRequest {
  nonce: number;
  builder: number[];
  maxFeeRate: string;
  hyperliquidChain: string;
  signatureChainId: string;
}

interface PermitRequest {
  tokenAddress: string;
  userWalletAddress: string;
  userBridgeAddress: string;
  permitValue: string;
  permitDeadline: string;
  permitSig: string;
}
```

## Error Handling

### Error Structure

All API errors follow this format:

```typescript theme={"system"}
interface ApiError {
  code: number;
  message: string;
  data?: any;
}
```

### Common Error Codes

* **400**: Bad Request - Invalid parameters
* **401**: Unauthorized - Authentication required
* **404**: Not Found - Resource doesn't exist
* **429**: Rate Limited - Too many requests
* **500**: Server Error - Internal server issue

### Error Handling Pattern

```typescript theme={"system"}
try {
  const result = await sdk.someOperation();
  // Handle success
} catch (error: any) {
  switch (error.code) {
    case 400:
      console.error('Validation error:', error.message);
      break;
    case 401:
      console.error('Authentication required');
      // Redirect to login
      break;
    case 429:
      console.error('Rate limited - retry later');
      break;
    default:
      console.error('Unexpected error:', error);
  }
}
```

## Rate Limits

* **Authentication**: 10 requests/minute
* **Trading Operations**: 60 requests/minute
* **Analytics**: 100 requests/minute
* **General Endpoints**: 200 requests/minute

## Configuration

### Environment Setup

```typescript theme={"system"}
// Initialize with custom base URL
const sdk = new SimpforFunSDK('https://api.simpfor.fun');

// Access token is managed automatically after authentication
// But you can also set it manually if needed
sdk.accessToken = 'your-token';
```

### Best Practices

**Connection Management**

* Reuse SDK instances
* Implement proper error handling
* Use retry logic with exponential backoff

**Data Management**

* Cache trader data locally when possible
* Use pagination for large datasets
* Implement reasonable polling intervals

**Security**

* Never expose access tokens client-side
* Use environment variables for configuration
* Validate inputs before API calls

## Support

**Documentation**

* [Integration Examples](/simpforfun/sdk-examples)
* [Getting Started Guide](/simpforfun/getting-started)
* [Platform Features](/simpforfun/features)

**Community**

* [GitHub](https://github.com/rkmonarch/simpfor-fun-sdk)

***

**Ready to build?** Check out our [Integration Examples](/simpforfun/sdk-examples) for complete implementation guides.