rain-sdk-v2 1.0.0

package/README.md

@@ -0,0 +1,1074 @@
+# Rain SDK V2
+
+TypeScript SDK for the Rain prediction markets protocol on Arbitrum One. Provides transaction builders for market creation, trading, liquidity management, order book operations, dispute resolution, and smart account (Account Abstraction) support.
+
+## Installation
+
+```bash
+npm install rain-sdk-v2 viem
+```
+
+### Optional (for Smart Account / Account Abstraction)
+
+```bash
+npm install @alchemy/aa-core @account-kit/infra @account-kit/wallet-client
+```
+
+## Quick Start
+
+```typescript
+import { Rain, RainAA, TradingModel, OptionSide } from 'rain-sdk-v2';
+import { createWalletClient, custom, parseUnits, parseEther } from 'viem';
+import { arbitrum } from 'viem/chains';
+
+// Initialize SDK
+const rain = new Rain({
+  environment: 'development', // 'development' | 'stage' | 'production'
+  rpcUrl: 'https://arb1.arbitrum.io/rpc', // optional, uses random public RPC if omitted
+});
+
+// Get environment config
+const config = rain.getEnvironmentConfig();
+console.log(config.usdt_token); // USDT contract address
+console.log(config.market_factory_address); // Factory contract
+```
+
+---
+
+## Classes
+
+### `Rain`
+
+Stateless class for building transactions and querying on-chain data. Does not require a wallet.
+
+#### Constructor
+
+```typescript
+const rain = new Rain(config?: RainCoreConfig);
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `environment` | `'development' \| 'stage' \| 'production'` | `'development'` | Target environment |
+| `rpcUrl` | `string` | Random public RPC | Custom Arbitrum RPC URL |
+| `apiUrl` | `string` | From environment | Custom API URL |
+
+---
+
+### `RainAA`
+
+Stateful class for smart account (Account Abstraction) management with Alchemy gas sponsorship.
+
+#### Constructor
+
+```typescript
+const rainAA = new RainAA(config: RainConfig);
+```
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `walletClient` | `WalletClient` | Yes | Viem wallet client |
+| `alchemyApiKey` | `string` | Yes | Alchemy API key |
+| `paymasterPolicyId` | `string` | Yes | Alchemy paymaster policy ID |
+| `chain` | `Chain` | Yes | Viem chain (e.g. `arbitrum`) |
+| `rpcUrl` | `string` | No | Custom RPC URL |
+
+#### Methods
+
+##### `connect()`
+
+Initializes the smart account. Returns the smart account address.
+
+```typescript
+const smartAccountAddress = await rainAA.connect();
+```
+
+##### `sendTransaction(rawTx: RawTransaction)`
+
+Sends a transaction from the smart account (gas-sponsored).
+
+```typescript
+const hash = await rainAA.sendTransaction(rawTx);
+```
+
+##### `disconnect()`
+
+Resets the connection state.
+
+```typescript
+rainAA.disconnect();
+```
+
+##### `address` (getter)
+
+Returns the smart account address. Throws if not connected.
+
+##### `client` (getter)
+
+Returns the smart wallet client instance. Throws if not connected.
+
+---
+
+## Transaction Builders
+
+All transaction builders return `RawTransaction` (or `RawTransaction[]` for multi-step operations):
+
+```typescript
+interface RawTransaction {
+  to: `0x${string}`;
+  data: `0x${string}`;
+  value?: bigint;
+}
+```
+
+---
+
+### Market Creation
+
+#### `buildCreateMarketTx(params: CreateMarketTxParams): Promise<RawTransaction[]>`
+
+Creates a new prediction market. Returns approval TX (if needed) + createPool TX.
+
+```typescript
+const txs = await rain.buildCreateMarketTx({
+  marketQuestion: 'Will ETH reach $5000 by end of 2025?',
+  marketOptions: ['Yes', 'No', 'Maybe'],
+  marketTags: ['crypto'],
+  marketDescription: 'Prediction on ETH price target',
+  isPublic: true,
+  isPublicPoolResolverAi: true, // true = AI resolver, false = manual resolver
+  creator: '0x...', // smart account or EOA address
+  startTime: BigInt(Math.floor(Date.now() / 1000) + 120), // 2 min from now
+  endTime: BigInt(Math.floor(Date.now() / 1000) + 86400), // 24h from now
+  no_of_options: 3n,
+  disputeTimer: 60, // seconds (set by SDK from environment)
+  inputAmountWei: parseUnits('10', 6), // 10 USDT initial liquidity
+  barValues: [33.33, 33.33, 33.34], // probability distribution (0-100, sums to 100)
+  baseToken: config.usdt_token, // USDT address
+  tradingModel: TradingModel.AMM, // AMM = 0, OrderBook = 1
+});
+
+// Approval amount = liquidity + (oracleFixedFeePerOption * numberOfOptions)
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `marketQuestion` | `string` | The market question |
+| `marketOptions` | `string[]` | Option labels (3-26 options) |
+| `marketTags` | `string[]` | Tags (1-3) |
+| `marketDescription` | `string` | Description |
+| `isPublic` | `boolean` | Public market |
+| `isPublicPoolResolverAi` | `boolean` | `true` for AI resolver, `false` for manual |
+| `creator` | `0x${string}` | Creator/pool owner address |
+| `startTime` | `bigint` | Unix timestamp (seconds) |
+| `endTime` | `bigint` | Unix timestamp (seconds) |
+| `no_of_options` | `bigint` | Number of options |
+| `inputAmountWei` | `bigint` | Initial liquidity in base token wei |
+| `barValues` | `number[]` | Probability distribution (0-100 scale) |
+| `baseToken` | `0x${string}` | Base token address (USDT) |
+| `tradingModel` | `TradingModel` | `AMM (0)` or `OrderBook (1)` |
+
+---
+
+### Trading
+
+#### `buildEnterOptionTx(params: EnterOptionTxParams): RawTransaction`
+
+Buy shares of an option (AMM trade).
+
+```typescript
+const tx = rain.buildEnterOptionTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1n, // 1-based option index
+  optionSide: OptionSide.Yes, // Yes = 1, No = 2
+  buyAmountInWei: parseUnits('5', 6), // 5 USDT
+});
+```
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `marketContractAddress` | `0x${string}` | Market contract address |
+| `selectedOption` | `bigint` | Option index (1-based) |
+| `optionSide` | `OptionSide` | `Yes (1)` or `No (2)` |
+| `buyAmountInWei` | `bigint` | Amount in base token wei |
+
+> **Note:** Requires prior ERC20 approval to the market contract.
+
+---
+
+### Split & Merge
+
+#### `buildSplitTx(params: SplitTxParams): RawTransaction`
+
+Split base tokens into equal Yes + No shares for an option.
+
+```typescript
+const tx = rain.buildSplitTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  amount: parseUnits('5', 6), // 5 USDT -> 5 Yes shares + 5 No shares
+});
+```
+
+> **Note:** Requires prior ERC20 approval to the market contract.
+
+#### `buildMergeTx(params: MergeTxParams): RawTransaction`
+
+Merge equal Yes + No share pairs back into base tokens.
+
+```typescript
+const tx = rain.buildMergeTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  amount: 5000000n, // raw shares amount (from getUserOptionShares)
+});
+```
+
+> **Note:** No approval needed. Burns your shares and returns base token.
+
+---
+
+### Liquidity
+
+#### `buildAddLiquidityTx(params: AddLiquidityTxParams): RawTransaction`
+
+Add liquidity to a specific option.
+
+```typescript
+const tx = rain.buildAddLiquidityTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  totalAmountInWei: parseUnits('10', 6), // 10 USDT
+});
+```
+
+> **Note:** Requires prior ERC20 approval to the market contract.
+
+#### `buildRemoveLiquidityTx(params: RemoveLiquidityTxParams): RawTransaction`
+
+Remove liquidity by burning LP shares.
+
+```typescript
+const lpShares = await rain.getUserOptionLPShares({
+  marketContractAddress: '0x...',
+  option: 1n,
+  userAddress: '0x...',
+});
+
+const tx = rain.buildRemoveLiquidityTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  lpShares, // raw LP shares amount
+});
+```
+
+---
+
+### Order Book
+
+#### `buildPlaceBuyOrderTx(params: PlaceBuyOrderTxParams): RawTransaction`
+
+Place a limit buy order.
+
+```typescript
+const tx = rain.buildPlaceBuyOrderTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSide: OptionSide.Yes,
+  price: parseEther('0.5'), // 50% price in 1e18 scale
+  amount: parseUnits('10', 6), // 10 USDT
+});
+```
+
+> **Note:** Requires prior ERC20 approval to the market contract. Available when AMM pool is closed.
+
+#### `buildPlaceSellOrderTx(params: PlaceSellOrderTxParams): RawTransaction`
+
+Place a limit sell order.
+
+```typescript
+const tx = rain.buildPlaceSellOrderTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSide: OptionSide.Yes,
+  price: parseEther('0.7'), // 70% price in 1e18 scale
+  shares: 5000000n, // shares to sell (from getUserOptionShares)
+});
+```
+
+> **Note:** No approval needed. Shares are escrowed by the contract.
+
+#### `buildCancelBuyOrdersTx(params: CancelBuyOrdersTxParams): RawTransaction`
+
+Cancel one or more buy orders.
+
+```typescript
+const tx = rain.buildCancelBuyOrdersTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSides: [1, 1], // Yes, Yes
+  prices: [parseEther('0.5'), parseEther('0.6')],
+  orderIDs: [1n, 2n], // from PlaceBuyOrder event
+});
+```
+
+#### `buildCancelSellOrdersTx(params: CancelSellOrdersTxParams): RawTransaction`
+
+Cancel one or more sell orders. Same interface as `buildCancelBuyOrdersTx`.
+
+---
+
+### Market Resolution
+
+#### `buildClosePoolAITx(params: ClosePoolAITxParams): Promise<RawTransaction[]>`
+
+Close a market pool with AI resolver. Returns approval (for resolver bond) + closePool TX.
+
+```typescript
+const txs = await rain.buildClosePoolAITx({
+  marketContractAddress: '0x...',
+  option: 1n,
+});
+```
+
+#### `buildClosePoolManualTx(params: ClosePoolManualTxParams): Promise<RawTransaction[]>`
+
+Close a market pool with manual resolver, proposing a winner side. Returns approval (for resolver bond) + closePool TX.
+
+```typescript
+const txs = await rain.buildClosePoolManualTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  proposedWinner: 1, // 1 = Yes, 2 = No
+});
+```
+
+#### `buildChooseWinnerTx(params: ChooseWinnerTxParams): RawTransaction`
+
+Finalize the winner after pool is closed.
+
+```typescript
+const tx = rain.buildChooseWinnerTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSide: 1, // 1 = Yes, 2 = No
+});
+```
+
+#### `buildCalculateWinnerTx(params: CalculateWinnerTxParams): Promise<RawTransaction>`
+
+Calculate winner via the oracle resolver. Must be called before `claim`. Reads `optionResolver(option)` from the market and calls `calculateWinner()` on that resolver contract.
+
+```typescript
+const tx = await rain.buildCalculateWinnerTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+});
+```
+
+---
+
+### Claiming
+
+#### `buildClaimTx(params: ClaimTxParams): RawTransaction`
+
+Claim winnings after market resolution. Call `buildCalculateWinnerTx` first.
+
+```typescript
+const tx = rain.buildClaimTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+});
+```
+
+---
+
+### Dispute / Appeal
+
+#### `buildOpenDisputeTx(params: OpenDisputeTxParams): Promise<RawTransaction[]>`
+
+Open a dispute (or appeal if dispute already exists). Returns approval (for dispute fee) + openDispute TX. The fee is read from `getDisputeAppealFee(option)`.
+
+```typescript
+const txs = await rain.buildOpenDisputeTx({
+  marketContractAddress: '0x...',
+  option: 1n,
+});
+```
+
+> **Note:** Call once to open dispute. Call again (after dispute window) to appeal.
+
+---
+
+### Token Approval
+
+#### `buildApprovalTx(params: ApproveTxParams): RawTransaction`
+
+Build an ERC20 approve transaction.
+
+```typescript
+const tx = rain.buildApprovalTx({
+  tokenAddress: config.usdt_token,
+  spender: '0x...', // market contract address
+  amount: parseUnits('100', 6), // 100 USDT
+});
+```
+
+---
+
+## Read Methods (On-Chain Queries)
+
+### `getTokenAllowance(params): Promise<bigint>`
+
+Check current ERC20 allowance.
+
+```typescript
+const allowance = await rain.getTokenAllowance({
+  tokenAddress: config.usdt_token,
+  owner: '0x...', // your address
+  spender: '0x...', // market contract
+});
+```
+
+### `getUserOptionLPShares(params): Promise<bigint>`
+
+Get user's LP shares for a specific option.
+
+```typescript
+const lpShares = await rain.getUserOptionLPShares({
+  marketContractAddress: '0x...',
+  option: 1n,
+  userAddress: '0x...',
+});
+```
+
+### `getUserOptionShares(params): Promise<bigint>`
+
+Get user's Yes or No shares for a specific option.
+
+```typescript
+const yesShares = await rain.getUserOptionShares({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSide: 1, // 1 = Yes, 2 = No
+  userAddress: '0x...',
+});
+```
+
+### `getUserActiveBuyOrders(params): Promise<bigint>`
+
+Get count of user's active buy orders.
+
+```typescript
+const count = await rain.getUserActiveBuyOrders({
+  marketContractAddress: '0x...',
+  userAddress: '0x...',
+});
+```
+
+### `getUserActiveSellOrders(params): Promise<bigint>`
+
+Get count of user's active sell orders.
+
+```typescript
+const count = await rain.getUserActiveSellOrders({
+  marketContractAddress: '0x...',
+  userAddress: '0x...',
+});
+```
+
+### `getFirstBuyOrderPrice(params): Promise<bigint>`
+
+Get the best (first) buy order price for an option/side.
+
+```typescript
+const price = await rain.getFirstBuyOrderPrice({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSide: 1, // Yes
+});
+// price is in 1e18 scale. 500000000000000000n = 0.5 = 50%
+```
+
+### `getFirstSellOrderPrice(params): Promise<bigint>`
+
+Get the best (first) sell order price for an option/side.
+
+### `getBuyOrdersAtPrice(params): Promise<OrderLevelInfo>`
+
+Get order book info at a specific price level.
+
+```typescript
+const info = await rain.getBuyOrdersAtPrice({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSide: 1,
+  price: parseEther('0.5'),
+});
+// { headIndex, tailIndex, count, isInitialized }
+```
+
+### `getSellOrdersAtPrice(params): Promise<OrderLevelInfo>`
+
+Same as above for sell orders.
+
+### `checkOrderExists(params): Promise<{ exists: boolean; index: bigint }>`
+
+Check if a specific order exists.
+
+```typescript
+const result = await rain.checkOrderExists({
+  marketContractAddress: '0x...',
+  option: 1n,
+  optionSide: 1,
+  price: parseEther('0.5'),
+  orderID: 1n,
+});
+```
+
+---
+
+## Authentication
+
+### `login(params: LoginParams): Promise<LoginResult>`
+
+Wallet-based login to the Rain backend.
+
+```typescript
+const result = await rain.login({
+  signature: '0x...', // personal_sign of lowercased wallet address
+  walletAddress: '0x...', // EOA address
+  smartWalletAddress: '0x...', // Smart account address
+  referredBy: 'CODE', // optional referral code
+});
+
+console.log(result.accessToken); // JWT token
+console.log(result.userId); // Backend user ID
+```
+
+---
+
+## Configuration
+
+### `getEnvironmentConfig()`
+
+Returns the current environment configuration.
+
+```typescript
+const config = rain.getEnvironmentConfig();
+```
+
+Returns:
+| Field | Description |
+|-------|-------------|
+| `apiUrl` | Backend API URL |
+| `market_factory_address` | Factory contract address |
+| `dispute_initial_timer` | Dispute timer in seconds |
+| `oracle_fixed_fee_per_option` | Oracle fee per option in base token wei |
+| `usdt_symbol` | USDT token symbol |
+| `usdt_token` | USDT token address |
+| `rain_token` | RAIN token address |
+
+---
+
+## Enums
+
+### `TradingModel`
+
+```typescript
+enum TradingModel {
+  AMM = 0,
+  OrderBook = 1,
+}
+```
+
+### `OptionSide`
+
+```typescript
+enum OptionSide {
+  Yes = 1,
+  No = 2,
+}
+```
+
+---
+
+## Environments
+
+| Environment | API | Factory |
+|-------------|-----|---------|
+| `development` | `https://dev-api.rain.one` | `0xBD99...0adE` |
+| `stage` | `https://stg-api.rain.one` | `0xD490...96BE` |
+| `production` | `https://prod-api.rain.one` | `0xA864...F264` |
+
+---
+
+## Typical Flow
+
+```
+1. Create Market (buildCreateMarketTx)
+2. Wait for startTime to pass
+3. Enter Option (buildEnterOptionTx) / Split (buildSplitTx)
+4. Place Orders (buildPlaceBuyOrderTx / buildPlaceSellOrderTx)
+5. Wait for endTime to pass
+6. Close Pool (buildClosePoolAITx / buildClosePoolManualTx)
+7. Calculate Winner (buildCalculateWinnerTx)
+8. Claim (buildClaimTx)
+```
+
+If disputed:
+```
+6b. Open Dispute (buildOpenDisputeTx)
+6c. Appeal (buildOpenDisputeTx again)
+```
+
+---
+
+## REST API Methods
+
+The SDK wraps all Rain backend REST API endpoints. Each method requires `accessToken` for authenticated routes.
+
+### Users
+
+```typescript
+// Find user by wallet address (public)
+const user = await rain.findUserByWalletAddress({ walletAddress: '0x...' });
+
+// Get authenticated user's profile
+const profile = await rain.getUserProfile(accessToken);
+
+// View another user's profile
+const profile = await rain.viewUserProfile({ userId: '...' }, accessToken);
+
+// Update profile
+await rain.updateUserProfile({
+  name: 'John',
+  bio: 'Trader',
+  profilePic: 'https://...',
+  twitterLink: 'https://...',
+}, accessToken);
+
+// Get total user count (public)
+const count = await rain.getUsersTotalCount();
+
+// Remove profile picture
+await rain.removeUserProfilePic(accessToken);
+
+// Get user activity history (deposits, withdrawals, trades, rewards)
+const history = await rain.getUserHistory({ limit: 20, offset: 1 }, accessToken);
+
+// Check if access token is still valid
+const status = await rain.checkTokenExpiration(accessToken);
+```
+
+### Comments
+
+```typescript
+// Create a comment
+await rain.createComment({ comment: 'Great market!', poolId: '...' }, accessToken);
+
+// Reply to a comment
+await rain.createComment({ comment: 'I agree', poolId: '...', parentCommentId: '...' }, accessToken);
+
+// Get comments for a pool
+const comments = await rain.getCommentsListing({ poolId: '...', limit: 10, offset: 0 });
+
+// Update a comment
+await rain.updateComment({ commentId: '...', comment: 'Updated text' }, accessToken);
+
+// Like / Unlike a comment
+await rain.likeComment({ commentId: '...' }, accessToken);
+await rain.unlikeComment({ commentId: '...' }, accessToken);
+
+// Get comment count for a pool
+const count = await rain.getCommentsCount({ poolId: '...' });
+```
+
+### Pools
+
+```typescript
+// Get public pools (paginated, filterable)
+const pools = await rain.getPublicPools({ limit: 10, offset: 0, status: 'Live', sortBy: 'trending' });
+
+// Get private pools
+const pools = await rain.getPrivatePools({ limit: 10, offset: 0 }, accessToken);
+
+// Get pool by ID
+const pool = await rain.getPoolById({ id: '...' });
+
+// Get pool by contract address
+const pool = await rain.getPoolByContractAddress({ contractAddress: '0x...' });
+
+// Search pools
+const results = await rain.searchPool({ query: 'bitcoin', limit: 10, offset: 0 });
+
+// Get featured pools
+const featured = await rain.getFeaturedPools({ limit: 10, offset: 0 });
+
+// Get all pools count
+const count = await rain.getAllPoolsCount();
+
+// Get related pools
+const related = await rain.getRelatedPools({ poolId: '...' });
+
+// Get pool resolution history (per sub-pool)
+const history = await rain.getPoolResolutionHistory({ poolId: '...', subPool: '...' });
+
+// Access a private pool
+const access = await rain.accessPool({ poolId: '...', accessCode: '1234' });
+
+// Verify access code
+await rain.verifyAccessCode({ poolId: '...', accessCode: '1234' }, accessToken);
+
+// Get pools created by a user
+const pools = await rain.getPoolListingByCreator({ limit: 10, offset: 0 }, accessToken);
+
+// Get total participants in a pool
+const count = await rain.getPoolTotalParticipants({ poolId: '...' });
+
+// Get total pools created by user
+const count = await rain.getTotalPoolsCreatedByUser(accessToken);
+
+// Get total predictions by user
+const count = await rain.getTotalPredictionsByUser(accessToken);
+
+// Update streaming status
+await rain.updateStreaming({ poolId: '...', streaming: true }, accessToken);
+
+// Update pool resolution time
+await rain.updatePoolResolutionTime({ poolId: '...', newEndDate: '...' }, accessToken);
+
+// Find pool fallback
+const pool = await rain.findPoolFallback({ poolId: '...' });
+
+// Sign oracles extend time
+await rain.signOraclesExtendTime({ poolId: '...' }, accessToken);
+```
+
+### Investments
+
+```typescript
+// Get user's total investment in a pool
+const investment = await rain.getUserTotalInvestment({ poolId: '...' }, accessToken);
+
+// Get options total volume for a pool
+const volume = await rain.getOptionsTotalVolume({ poolId: '...' });
+
+// Get pool activity (trades)
+const activity = await rain.getPoolActivity({ poolId: '...', limit: 10, offset: 0 });
+
+// Get top holders in a pool
+const holders = await rain.getTopHolders({ poolId: '...', limit: 10, offset: 0 });
+
+// Get user's invested pools
+const pools = await rain.getUserInvestedPools({ limit: 10, offset: 0 }, accessToken);
+
+// Get platform TVL
+const tvl = await rain.getPlatformTvl();
+
+// Get investment volume graph
+const graph = await rain.getInvestmentVolumeGraph({ period: '7d' }, accessToken);
+
+// Calculate user PNL
+const pnl = await rain.calculateUserPnl({ walletAddress: '0x...' }, accessToken);
+
+// Get user total volume
+const volume = await rain.calculateUserTotalVolume(accessToken);
+
+// Get PNL graph
+const graph = await rain.getUserPnlGraph({ period: '30d' }, accessToken);
+
+// Get TVL graph
+const graph = await rain.getTvlGraph();
+
+// Get PNL per pool
+const pnl = await rain.calculateUserPnlPerPool(accessToken);
+
+// Get PNL by specific pool
+const pnl = await rain.getPnlByPoolId({ poolId: '...' }, accessToken);
+
+// Get top winners and losers
+const leaderboard = await rain.getTopWinnersLosers({ limit: 10, period: '7d' });
+
+// Get user overall investment
+const overall = await rain.getUserOverallInvestment(accessToken);
+
+// Get platform volume
+const volume = await rain.getPlatformVolume();
+
+// Get user invested live pools count
+const count = await rain.getUserInvestedLivePoolsCount(accessToken);
+
+// Calculate user open interest
+const oi = await rain.calculateUserOpenInterest(accessToken);
+```
+
+### Orders
+
+```typescript
+// Get user's orders
+const orders = await rain.getUserOrders({ limit: 10, offset: 1, filter: 'pending' }, accessToken);
+
+// Get order book for a pool
+const book = await rain.getOrderBook({ pool: '...' });
+
+// Get user's orders for a specific pool
+const orders = await rain.getUserOrderByPoolId({ poolId: '...' }, accessToken);
+
+// Get all orders for a pool
+const orders = await rain.getOrdersListingByPool({ pool: '...', limit: 10, offset: 1 });
+
+// Get order by ID
+const order = await rain.getOrderById({ orderId: '...' });
+```
+
+### Points
+
+```typescript
+// Get user points
+const points = await rain.getUserPoints(accessToken);
+
+// Get user points graph
+const graph = await rain.getUserPointsGraph(accessToken);
+
+// Add user points
+await rain.addUserPoints({ points: 100, reason: '...' }, accessToken);
+
+// User successful onboarding
+await rain.userSuccessfulOnboarding({ step: '...' }, accessToken);
+```
+
+### Notifications
+
+```typescript
+// Get notifications
+const notifs = await rain.getNotifications({ limit: 20, offset: 0 }, accessToken);
+
+// Mark all as read
+await rain.markAllNotificationsAsRead(accessToken);
+
+// Mark single notification as read
+await rain.markNotificationAsRead({ notificationId: '...' }, accessToken);
+```
+
+### Price Data
+
+```typescript
+// Get price data for a pool
+const prices = await rain.getPriceData({ poolId: '...', interval: '1h' });
+```
+
+### Pool Reviews
+
+```typescript
+// Add review
+await rain.addReview({ poolId: '...', rating: 5, review: 'Great!' }, accessToken);
+
+// Get user's reviews
+const reviews = await rain.getUserReviews(accessToken);
+
+// Get pools by creator with reviews
+const pools = await rain.getPoolsByCreatorReviews(accessToken);
+```
+
+### Follow
+
+```typescript
+// Toggle follow a user
+await rain.toggleFollow({ userId: '...' }, accessToken);
+
+// Check if following
+const status = await rain.checkFollow({ userId: '...' }, accessToken);
+
+// Get followers
+const followers = await rain.getFollowers({ userId: '...', limit: 20, offset: 0 });
+
+// Get following
+const following = await rain.getFollowing({ userId: '...', limit: 20, offset: 0 });
+
+// Get follow stats
+const stats = await rain.getFollowStats({ userId: '...' });
+```
+
+### Rain Burn
+
+```typescript
+// Get total RAIN burned
+const burned = await rain.getTotalBurned();
+
+// Get burn per pool
+const burn = await rain.getBurnPerPool({ poolId: '...' });
+```
+
+### Dispute
+
+```typescript
+// Create dispute message (with optional file upload)
+await rain.createDisputeMessage({
+  pool: '...',
+  role: 'disputer',
+  messageType: 'text',
+  evidence: { description: '...' },
+}, accessToken);
+
+// Get dispute conversation for a sub-pool
+const convo = await rain.getPoolDisputeConvo({ poolId: '...', subPool: '...', limit: 50, offset: 0 }, accessToken);
+```
+
+---
+
+## WebSocket Events (Socket.IO)
+
+Real-time event subscriptions via Socket.IO.
+
+### Setup
+
+```typescript
+import { RainSocket } from 'rain-sdk-v2';
+
+const socket = new RainSocket('https://dev-api.rain.one');
+socket.connect();
+```
+
+### Pool-Scoped Events
+
+Subscribe to events for a specific pool using `poolId`:
+
+```typescript
+// Trading events
+const unsub = socket.onEnterOption(poolId, (data) => {
+  console.log(data.enterOption, data.pool, data.subPool);
+});
+
+socket.onExitOption(poolId, (data) => { /* data.exitOption, pool, subPool */ });
+socket.onLiquidity(poolId, (data) => { /* data.enterLiquidity, pool, subPool */ });
+socket.onSplit(poolId, (data) => { /* data.split, pool, subPool */ });
+socket.onMerge(poolId, (data) => { /* data.merge, pool, subPool */ });
+socket.onRemoveLiquidity(poolId, (data) => { /* data.removeLiquidity, pool, subPool */ });
+
+// Price updates
+socket.onSyncPrice(poolId, (data) => {
+  // data.prices = [{ side: 1, price: 0.62, percentage: 62, subPoolIndex: 1 }, ...]
+  // data.pool, data.subPool
+});
+
+// Order book events
+socket.onOrderCreated(poolId, (data) => { /* data.order, pool, subPool */ });
+socket.onOrderCancelled(poolId, (data) => { /* data.order, pool, subPool */ });
+socket.onOrderFilled(poolId, (data) => { /* data.filledOrder, data.pendingOrder?, pool, subPool */ });
+
+// Pool lifecycle
+socket.onPoolClosed(poolId, (data) => { /* data.pool, data.subPool? */ });
+socket.onPoolReverted(poolId, (data) => { /* data.pool, data.subPool */ });
+socket.onPoolTokenSet(poolId, (data) => { /* data.pool */ });
+socket.onStreamingStatusChanged(poolId, (data) => { /* data.pool */ });
+
+// Resolution events
+socket.onWinner(poolId, (data) => { /* data.pool, data.subPool */ });
+socket.onWinnerProposer(poolId, (data) => { /* data.pool, data.subPool */ });
+socket.onRevealWinnerAvailable(poolId, (data) => { /* data.subPoolId */ });
+
+// Dispute & Appeal events
+socket.onDisputeOpened(poolId, (data) => { /* data.subPool, data.eventType */ });
+socket.onOracleCreated(poolId, (data) => { /* data.pool, data.subPool */ });
+socket.onDisputeTimeExtended(poolId, (data) => { /* data.pool, data.subPool */ });
+socket.onAppealOpened(poolId, (data) => { /* data.pool, data.subPool */ });
+socket.onAppealWinnerCalculated(poolId, (data) => { /* data.subPool */ });
+socket.onDisputeWinner(poolId, (data) => { /* data.subPool, data.eventType */ });
+socket.onAppealWinner(poolId, (data) => { /* data.subPool, data.eventType, data.winnerFinalized */ });
+
+// Claim events (pool-scoped broadcast)
+socket.onClaimReward(poolId, (data) => { /* data.claimReward, pool, subPool */ });
+```
+
+### User-Scoped Events
+
+Events targeted to a specific user (require `userId`):
+
+```typescript
+// Personal claim reward
+socket.onUserClaimReward(poolId, userId, (data) => { /* data.claimReward, pool, subPool */ });
+
+// Dispute bond refunded (disputer won)
+socket.onDisputeRefund(poolId, userId, (data) => { /* data.claimReward, pool, subPool */ });
+
+// Appeal fee refunded (appealer won)
+socket.onAppealRefund(poolId, userId, (data) => { /* data.claimReward, pool, subPool */ });
+
+// Resolution bond refunded (proposer was correct)
+socket.onResolutionRefund(poolId, userId, (data) => { /* data.claimReward, pool, subPool */ });
+
+// Resolver closing share reward
+socket.onResolverReward(poolId, userId, (data) => { /* data.claimReward, pool, subPool */ });
+
+// Personal notifications
+socket.onNotifications(userId, (data) => {
+  // data._id, userId, type, message, pool, subPool, createdAt, read
+});
+```
+
+### Global Events
+
+```typescript
+// New pool created
+socket.onNewPool((data) => { /* data.pool, data.subMarkets */ });
+```
+
+### Generic Subscription
+
+```typescript
+// Subscribe to any channel directly
+const unsub = socket.onChannel('custom-event/123', (data) => { ... });
+
+// Unsubscribe
+unsub();
+```
+
+### Cleanup
+
+```typescript
+socket.disconnect();
+```
+
+### All Socket Event Channels
+
+| Channel | Description |
+|---------|-------------|
+| `pool` | New pool created |
+| `pool-token-set/{poolId}` | Token set for pool |
+| `pool-closed/{poolId}` | Pool/SubPool finalized |
+| `pool-reverted/{poolId}` | Resolution reverted |
+| `streamingStatusChanged/{poolId}` | Streaming toggled |
+| `enter-option/{poolId}` | Shares bought (AMM or order match) |
+| `exit-option/{poolId}` | Shares sold (order match) |
+| `liquidity/{poolId}` | Liquidity added |
+| `split/{poolId}` | Tokens split into Yes+No |
+| `merge/{poolId}` | Yes+No merged back |
+| `remove-liquidity/{poolId}` | Liquidity removed |
+| `sync-price/{poolId}` | Price update |
+| `order-created/{poolId}` | New order placed |
+| `order-cancelled/{poolId}` | Order cancelled |
+| `order-filled/{poolId}` | Order filled (full/partial) |
+| `winner/{poolId}` | Winner proposed |
+| `winner-proposer/{poolId}` | Proposer recorded |
+| `reveal-winner-available/{poolId}` | Appeal winner ready |
+| `dispute-opened/{poolId}` | Dispute opened |
+| `oracle-created/{poolId}` | Dispute oracle deployed |
+| `dispute-time-extented/{poolId}` | Deadline extended |
+| `appeal-opened/{poolId}` | Appeal filed |
+| `appeal-winner-calculated/{poolId}` | Oracle calculated winner |
+| `dispute-winner/{poolId}` | Dispute decided (LEX) |
+| `appeal-winner/{poolId}` | Final appeal winner |
+| `claim-reward/{poolId}` | Reward claimed (broadcast) |
+| `claim-reward/{poolId}/{userId}` | Reward claimed (personal) |
+| `dispute-refund/{poolId}/{userId}` | Dispute bond refunded |
+| `appeal-refund/{poolId}/{userId}` | Appeal fee refunded |
+| `resolution-refund/{poolId}/{userId}` | Resolution bond refunded |
+| `resolver-reward/{poolId}/{userId}` | Resolver reward |
+| `notifications/{userId}` | Personal notifications |
+
+---
+
+## License
+
+MIT