@rainprotocolsdk/sdk 2.1.2 → 2.3.0

package/README.md

@@ -1,932 +1,952 @@
-# Rain SDK Documentation
+# Rain Builders — SDK Guide
 
-## Overview
+Build complete prediction markets, trading applications, and custom integrations powered by Rain's automated protocol.
 
-Rain SDK is designed as a **clean, modular, and extensible TypeScript SDK** for interacting with Rain markets and preparing on-chain transactions.
+The Rain SDK provides the TypeScript tools you need to interact with our protocol on Arbitrum One. You can use it to build, sign, and send transactions for everything from creating new markets to trading options and claiming winnings.
 
-The SDK is intentionally split into two layers:
+Whether you're building a custom frontend, routing trades for your users, or launching specialized pools, the SDK handles the technical execution. By integrating Rain, you plug directly into our automated market maker (AMM) liquidity for logic-based forecasts.
 
-* **Rain** → Stateless, public-facing utilities (data fetching, raw transaction builders)
-* **RainAA** → Stateful Account Abstraction layer (smart accounts)
+If you're building high-speed applications, you can tap into our **RNG Layer**. This system uses verifiable randomness through Chainlink VRF to power mathematically-driven risk scenarios. Instead of using the individual pools required for standard prediction markets, the RNG Layer draws from a single shared liquidity pool. This gives your users instant settlement for fast-paced, random markets across any application built on this layer.
 
----
+You can also give your users a simpler trading experience. The SDK includes an **account abstraction module**. This lets you manage smart accounts and sponsor gas fees, so your users can trade without worrying about network costs.
 
-## Installation
+Our Builder Program supports platforms that drive volume or create unique markets. You bring the users and the ideas, and the SDK provides the on-chain infrastructure.
 
-```bash
-npm install @rainprotocolsdk/sdk
-```
+---
 
-or
+## What You Can Build
 
-```bash
-yarn add @rainprotocolsdk/sdk
-```
+The SDK gives you direct access to the protocol's core functions. Here is what you can do right away.
 
----
+- **Permissionless Market Creation** — Launch public or private markets on any verifiable event. You define the options, set the resolution rules, and provide the initial liquidity in a single transaction. Rain is open for anyone to build on, so you never need our approval to start a new pool.
+- **Trading** — Construct interfaces for your users to buy and sell outcome shares against the AMM with market and limit orders.
+- **Gas-Sponsored Execution** — Route transactions through the `RainAA` module. We use Alchemy smart accounts to cover gas costs. Your users can trade and interact with the protocol without needing to hold native ETH in their wallets.
+- **Live Data Streams** — Connect to our WebSockets via `RainSocket` to receive real-time trade events, order activity, dispute updates, and market resolution notifications directly in your front end.
 
-### Initialization
+---
 
-```ts
-import { Rain } from "@rainprotocolsdk/sdk";
+## SDK Architecture: The Two Pillars
 
-const rain = new Rain();
-```
+The SDK is split into two independent classes. This structure separates the logical transaction building from the actual execution.
 
-### Constructor Parameters
+| Module | Role | Core Functions | Wallet Required |
+| ------------------- | ---------------------- | ------------------------------------------------------------------- | --------------- |
+| `Rain` (Stateless)  | Defines **what** to do | Market queries, transaction builders | No |
+| `RainAA` (Stateful) | Defines **how** to execute | Smart account creation, gas-sponsored execution, session management | Yes |
 
-```ts
-interface RainCoreConfig {
-  environment?: "development" | "stage" | "production"; // default: "development"
-  rpcUrl?: string; // optional custom RPC URL
-}
-```
+### The Execution Flow
 
----
+1. **Your Application** — The user interacts with your custom frontend.
+2. **The `Rain` Class** — Your application calls a method here to build an action. All transaction builders return an unsigned `RawTransaction` containing the `to`, `data`, and optional `value` fields.
+3. **The `RainAA` Class** — You pass that `RawTransaction` into this module. It manages the Alchemy smart accounts and signs the transaction via account abstraction, covering the network fees.
+4. **Arbitrum One** — The transaction settles on-chain, interacting with our Diamond Proxy pools and the specific AMM for that option.
 
-## login
+### The `Rain` Class (Stateless)
 
-Authenticates a user against the Rain backend using a wallet signature and returns a JWT access token.
+`Rain` operates without state. It fetches data and builds unsigned transactions. It does not require a connected wallet.
 
-The caller is responsible for signing the message — pass the resulting signature along with the wallet addresses.
+You use this class to query the protocol and construct actions. Because it returns a standard `RawTransaction`, you retain the freedom to decide how to execute it — whether you use `RainAA`, `wagmi`, `ethers`, or another custom provider.
 
-### Method Signature
+### The `RainAA` Class (Stateful Execution)
 
-```ts
-login(params: LoginParams): Promise<LoginResult>
-```
+`RainAA` maintains state. It handles the mechanics of account abstraction.
 
-### Parameters
+Once your stateless class generates the transaction data, you pass it here. This module takes care of the execution. It sponsors gas costs so your users do not need native ETH to trade.
 
-```ts
-interface LoginParams {
-  signature: string;          // personal_sign of the lowercased wallet address
-  walletAddress: string;      // EOA wallet address
-  smartWalletAddress: string; // Smart account / AA wallet address
-  referredBy?: string;        // Optional referral code
-}
-```
+---
 
-### Return Type
+## Quick Start
 
-```ts
-interface LoginResult {
-  accessToken: string; // JWT token for authenticated API calls
-  userId: string;      // Backend user ID
-}
-```
+The Rain SDK is designed to get you reading data and building transactions as quickly as possible. Because the core `Rain` class is stateless, you can start fetching markets and building trade payloads without requiring users to connect a wallet upfront.
 
-### Example
+### Installation
 
-```ts
-// 1. Sign the message with your wallet provider
-const signature = await walletClient.signMessage({
-  message: walletAddress.toLowerCase(),
-});
+First, install the SDK into your project using your preferred package manager.
 
-// 2. Login
-const { accessToken, userId } = await rain.login({
-  signature,
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  smartWalletAddress: "0xSmartAccountAddress...",
-  referredBy: "REFCODE123", // optional
-});
+```bash
+npm install @rainprotocolsdk/sdk
+npm install viem@^2.0.0  # Required peer dependency
 ```
 
----
+### Your First Trade Flow
 
-## getPublicMarkets
+Here is a complete example of how you initialize the client, read active markets from the protocol, build a transaction to buy shares, and execute it.
 
-Fetches public market data from the Rain backend.
+**1. Initialize (stateless — no wallet needed)**
 
-### Method Signature
+You set up the `Rain` class by pointing it to the development environment. This automatically configures the correct factory addresses and API endpoints.
 
 ```ts
-getPublicMarkets(params: GetMarketsParams): Promise<Market[]>;
+const rain = new Rain({ environment: 'development' });
 ```
 
-### Parameters
-
-```ts
-interface GetMarketsParams {
-  limit?: number;
-  offset?: number;
-  sortBy?: "Liquidity" | "Volumn" | "latest";
-  status?: 'Live' | 'New' | 'WaitingForResult' | 'UnderDispute' | 'UnderAppeal' | 'ClosingSoon' | 'InReview' | 'InEvaluation' | 'Closed' | 'Trading';
-}
-```
+**2. Fetch Markets**
 
-### Example
+You query the protocol for a list of active markets. This pulls data directly from the Rain API.
 
 ```ts
-const markets = await rain.getPublicMarkets({
-  limit: 12,
-  offset: 1,
-  sortBy: "Liquidity",
-  status: "Live",
-});
+const markets = await rain.getPublicMarkets({ limit: 10 });
 ```
 
----
-
-## getMarketById
-
-Fetches a single market by its ID from the Rain backend.
+**3. Build a Buy Transaction**
 
-### Method Signature
+You define exactly what you want to do. In this case, you are building the raw transaction data to buy $10 worth of shares in Option 1.
 
 ```ts
-getMarketById(params: GetMarketByIdParams): Promise<Market>
+const rawTx = rain.buildBuyOptionRawTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1n,
+  buyAmountInWei: 10_000_000n, // 10 USDT (Arbitrum USDT uses 6 decimals)
+});
 ```
 
-### Parameters
+**4. Execute**
+
+The SDK hands you back an unsigned `RawTransaction` (`{ to, data, value }`). You then pass this payload to your user's standard wallet provider, or route it through the `RainAA` class for gasless execution.
 
 ```ts
-interface GetMarketByIdParams {
-  marketId: string; // MongoDB _id of the market
-}
+await yourProvider.sendTransaction(rawTx);
 ```
 
-### Validations
+---
 
-| Parameter  | Type     | Required | Description            |
-| ---------- | -------- | -------- | ---------------------- |
-| `marketId` | `string` | ✅        | Unique market `_id`    |
+## Authentication
 
-### Example
+Before accessing protected endpoints, users must authenticate with the Rain API.
 
 ```ts
-const market = await rain.getMarketById({
-  marketId: "698c8f116e985bbfacc7fc01",
+const result = await rain.login({
+  walletAddress: '0x996ea23940f4a01610181D04bdB6F862719b63f0',
+  signature: '0x...', // Signed message from user's wallet
 });
+// Returns: { accessToken, userId, ... }
 ```
 
+The `accessToken` returned is required for methods that need user context, such as `getUserInvestments`, `buildClaimTx`, and `buildExtendTimeTx`.
+
 ---
 
-## getUserInvestments
+## Creating a Market
 
-Fetches a user's invested markets from the Rain backend. Requires a valid access token.
+Launch your own prediction markets on any verifiable event.
 
-### Method Signature
+One of the core features of building on Rain is permissionless market creation. You do not need approval to start a new pool. If an event has a verifiable outcome, you can build a market around it using the SDK.
 
-```ts
-getUserInvestments(params: GetUserInvestmentsParams): Promise<UserInvestment[]>
-```
+When you create a market, you define the question, set the possible options, and provide the initial liquidity. This liquidity allows the Automated Market Maker (AMM) to start pricing shares immediately.
 
-### Parameters
+### Public vs. Private Markets
 
-```ts
-interface GetUserInvestmentsParams {
-  walletAddress: string;  // User's wallet address
-  accessToken: string;    // JWT from Rain auth (login)
-  limit?: number;
-  offset?: number;
-  status?: 'Live' | 'New' | 'WaitingForResult' | 'UnderDispute' | 'UnderAppeal' | 'ClosingSoon' | 'InReview' | 'InEvaluation' | 'Closed' | 'Trading';
-}
-```
+Before writing the code, you need to decide what kind of market you are building using the `isPublic` parameter.
+
+- **Public Markets** — These are open to anyone and are great for topics like sports, politics, or global events. The market can be resolved either by a specialized AI oracle or by the market creator.
+- **Private Markets** — These are designed for specific groups or topics and require a secret access code to join. The person who creates the pool acts as the resolver and decides the outcome.
 
-### Validations
+### Building the Transaction
 
-| Parameter       | Type          | Required | Description                          |
-| --------------- | ------------- | -------- | ------------------------------------ |
-| `walletAddress` | `string`      | ✅        | The user's wallet address            |
-| `accessToken`   | `string`      | ✅        | JWT returned from `login()`          |
-| `limit`         | `number`      | ❌        | Number of results per page           |
-| `offset`        | `number`      | ❌        | Pagination offset                    |
-| `status`        | `MarketStatus`| ❌        | Filter by market status              |
+You use the stateless `Rain` class to construct the transaction. The `buildCreateMarketTx` method requires specific parameters to set the probabilities, dates, and token decimals.
 
-### Example
+Because creating a market usually requires approving the token spend first, this method returns an array of raw transactions that you must execute in order.
 
 ```ts
-const investments = await rain.getUserInvestments({
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  accessToken: "eyJhbGciOi...",
-  limit: 10,
-  offset: 1,
-  status: "Live",
+import { Rain } from '@rainprotocolsdk/sdk';
+
+const rain = new Rain({ environment: 'production' });
+
+// buildCreateMarketTx returns an array: [approveTx, createTx] or just [createTx]
+const txs = await rain.buildCreateMarketTx({
+  marketQuestion: 'Will BTC hit 100k?',
+  marketOptions: ['Yes', 'No', 'Maybe'],
+  marketTags: ['crypto', 'bitcoin'],
+  marketDescription: 'Prediction market for BTC price',
+  isPublic: true,
+  isPublicPoolResolverAi: false,
+  creator: '0x996ea23940f4a01610181D04bdB6F862719b63f0',
+  startTime: 1770836400n,
+  endTime: 1770922800n,
+  no_of_options: 3n,
+  inputAmountWei: 100_000_000n,  // 100 USDT (min 10 tokens)
+  barValues: [34, 33, 33],       // Initial probability distribution (%)
+  baseToken: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
+  tokenDecimals: 6,
 });
+
+// Execute sequentially
+for (const tx of txs) {
+  await yourProvider.sendTransaction(tx);
+}
 ```
 
+### Breaking Down the Parameters
+
+- **Text Fields** — `marketQuestion`, `marketDescription`, and `marketTags` define how the market appears to users.
+- **Options** — `marketOptions` is an array of the possible outcomes. `no_of_options` is the numerical count of those choices.
+- **Permissions** — `isPublic` determines if the market is open or access-restricted. `isPublicPoolResolverAi` dictates if the AI oracle handles the resolution.
+- **Timing** — `startTime` and `endTime` are Unix timestamps defining when the market is active.
+- **Liquidity & Tokens** — `inputAmountWei` is your initial funding. The minimum requirement is $10 in the chosen token. `baseToken` is the contract address of the currency being used, and `tokenDecimals` ensures the math is calculated correctly.
+- **Initial Odds** — `barValues` sets the starting probability distribution for the options as a percentage. All values must sum to 100.
+
+### Managing the Market Lifecycle
+
+Creating the market is just the first step. To manage the conclusion of a market, the SDK provides these transaction builders:
+
+- `buildCloseMarketTx(params)` — Builds a raw transaction to officially close the market and halt trading.
+- `buildCreateDisputeTx(params)` — Builds a raw transaction to open a dispute on the market outcome.
+- `buildCreateAppealTx(params)` — Builds a raw transaction to appeal a dispute decision.
+- `buildExtendTimeTx(params)` — Builds a raw transaction to extend the dispute resolution window (re-submit appeal).
+
 ---
 
-## buildApprovalTx
+## Trading & Positions
 
-Builds a raw ERC20 approval transaction if needed.
+Build interfaces for buying shares, placing limit orders, and claiming winnings.
 
-This function prepares an unsigned `approve(spender, amount)` transaction and does not execute it.
+Once a market is live, participants can start taking positions. The Rain SDK allows you to construct trading actions directly from the protocol.
 
-If `amount` is not provided, a default large allowance is approved.
+Because trades happen against our Automated Market Maker (AMM), your users get instant execution. They do not have to wait for a counterparty to match their order.
 
-### Return Type
+### Buying Options
 
-```ts
-interface RawTransaction {
-  to: `0x${string}`;
-  data: `0x${string}`;
-}
-```
+When a user buys an option, they are purchasing shares of a specific outcome. The price of these shares is determined by the AMM based on the current pool ratios.
 
-### Example
+Here is how you build a standard market order to buy shares.
 
 ```ts
-const approvalTx = rain.buildApprovalTx({
-  tokenAddress: "0xTokenAddress...",  // ERC20 token address
-  spender: "0xMarketContractAddress...", // Market contract address
-  amount: 1000000000000000000n // optional
+import { Rain } from '@rainprotocolsdk/sdk';
+
+const rain = new Rain({ environment: 'production' });
+
+// Build the raw buy transaction
+const buyTx = rain.buildBuyOptionRawTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1n,          // The option index (e.g., 0 for Yes, 1 for No)
+  buyAmountInWei: 10_000_000n, // 10 USDT (Arbitrum USDT uses 6 decimals)
 });
 ```
 
----
-
-## buildBuyOptionRawTx
+If a user wants to set a specific entry target rather than taking the current AMM price, you can build a limit order instead.
 
-Builds a **raw EVM transaction** for entering a market option.
+```ts
+// Build a limit buy transaction
+const limitTx = rain.buildLimitBuyOptionTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1,
+  pricePerShare: 500000000000000000n, // 0.50 represented in 1e18
+  buyAmountInWei: 10_000_000n,
+  tokenDecimals: 6,
+});
+```
 
-This function **does not send the transaction** — it only prepares calldata.
+### Selling Options
 
-### Method Signature
+Users do not have to hold their shares until the market resolves. If the odds shift in their favor, they can sell their position early to lock in a profit.
 
 ```ts
-buildBuyOptionRawTx(params: EnterOptionTxParams): RawTransaction;
+// Build a limit sell transaction
+const sellTx = rain.buildLimitSellOptionTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1,
+  pricePerShare: 500000000000000000n, // 0.50 represented in 1e18
+  shares: 5_000_000n,                 // The number of shares to sell
+  tokenDecimals: 6,
+});
 ```
 
-### Parameters
+### Canceling Orders
+
+If a user places limit orders that have not been filled yet, they might want to cancel them. You can build a transaction to remove specific open orders by referencing their order IDs, or cancel all open orders at once.
 
 ```ts
-interface EnterOptionTxParams {
-  marketContractAddress: `0x${string}`; // TradeMarket contract address
-  selectedOption: bigint;               // Option index
-  buyAmountInWei: bigint;               // Amount in wei
-}
+// Build a transaction to cancel specific open orders
+const cancelTx = rain.buildCancelOrdersTx({
+  marketContractAddress: '0x...',
+  orders: [
+    { option: 1, price: 0.5, orderID: 1n },
+    { option: 1, price: 0.6, orderID: 2n },
+  ],
+});
+
+// Build a transaction to cancel all open orders for a user
+const cancelAllTx = await rain.buildCancelAllOpenOrdersTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
 ```
 
-### Return Type
+### Claiming Winnings
 
-```ts
-interface RawTransaction {
-  to: `0x${string}`;
-  data: `0x${string}`;
-}
-```
+When a market concludes, it goes through a resolution phase and a short dispute window. Once that window closes, the market is officially settled.
 
-### Example
+Users who hold shares in the winning outcome can then claim their payout. The payout is drawn from the total pool of funds, after a platform fee is collected.
 
 ```ts
-const rawTx = rain.buildBuyOptionRawTx({
-  marketContractAddress: "0xMarketContractAddress...",
-  selectedOption: 1n,
-  buyAmountInWei: 1000000n,
+// Build the raw claim transaction
+const claimTx = await rain.buildClaimTx({
+  marketId: '698c8f116e985bbfacc7fc01',
+  walletAddress: '0x996ea23940f4a01610181D04bdB6F862719b63f0',
 });
 ```
 
+This single transaction sends the user's original stake plus their winnings directly to their wallet or smart account.
+
 ---
 
-## buildLimitBuyOptionTx
+## Liquidity
 
-Builds a **raw EVM transaction** for placing a limit buy order on a Rain market.
+Every market on Rain needs liquidity to function. Because trades execute against an Automated Market Maker (AMM), the pool requires an initial supply of funds to price shares and settle outcomes.
 
-This function **does not send the transaction** — it only prepares calldata.
+### Adding Liquidity
 
-### Method Signature
+Use `buildAddLiquidityTx` to let users supply funds to an existing market. The SDK reads the market's base token on-chain and only requests the approval needed — either USDT or RAIN, depending on the market.
 
 ```ts
-buildLimitBuyOptionTx(params: EnterLimitOptionTxParams): RawTransaction
-```
-
-### Parameters
+const txs = await rain.buildAddLiquidityTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  amount: 100,  // human-readable amount — decimals auto-detected (6 for USDT, 18 for RAIN)
+});
 
-```ts
-interface EnterLimitOptionTxParams {
-  marketContractAddress: `0x${string}`; // Market contract address
-  selectedOption: number;               // Option index
-  pricePerShare: number;                // Limit price per share (between 0 and 1)
-  buyAmountInWei: bigint;               // Total buy amount in token wei
-  tokenDecimals?: number;               // Token decimals (default: 6)
+// Execute sequentially
+for (const tx of txs) {
+  await yourProvider.sendTransaction(tx);
 }
 ```
 
-### Validations
+Returns `[approveTx, enterLiquidityTx]` if the allowance is insufficient, or `[enterLiquidityTx]` if already approved.
 
-| Field                   | Type          | Required | Description                                            |
-| ----------------------- | ------------- | -------- | ------------------------------------------------------ |
-| `marketContractAddress` | `0x${string}` | ✅        | Address of the market contract                         |
-| `selectedOption`        | `number`      | ✅        | Option index to place the buy order for                |
-| `pricePerShare`         | `number`      | ✅        | Limit price per share (between `0` and `1`)            |
-| `buyAmountInWei`        | `bigint`      | ✅        | Total amount to spend (already converted to token wei) |
-| `tokenDecimals`         | `number`      | ❌        | Token decimals (default: `6`)                          |
+### How LPs Earn Fees
 
-### Return Type
+Liquidity providers take on the other side of the trades. They fund the entire market rather than betting on "Yes" or "No". In return for taking on this risk, they earn a cut of the trading activity.
 
-```ts
-interface RawTransaction {
-  to: `0x${string}`;
-  data: `0x${string}`;
-}
-```
+The protocol charges a 5% fee on transactions. From that total volume, 1.2% is automatically distributed back to the liquidity providers of that specific market.
 
-### Example
+For applications built on the RNG Layer, like Risk Markets, liquidity providers act as the "house". They still earn the 1.2% volume fee. Additionally, if players fail to exit their positions before a scenario terminates, their stakes remain in the pool, which increases the value of the LP shares.
 
-```ts
-rain.buildLimitBuyOptionTx({
-  marketContractAddress: "0xMarketContractAddress...",
-  selectedOption: 1,
-  pricePerShare: 0.6,
-  buyAmountInWei: 1000000n,
-});
-```
+### Withdrawing Liquidity
 
----
+Liquidity is locked until the market reaches its resolution. There is no method to remove liquidity while the market is active.
 
-## buildLimitSellOptionTx
+Liquidity providers recover their initial supplied share, plus any accumulated fees, by using the standard `buildClaimTx` method after the market officially resolves and settles.
 
-Builds a **raw EVM transaction** for placing a limit sell order on a Rain market.
+---
 
-This function **does not send the transaction** — it only prepares calldata.
+## Disputes & Appeals
 
-### Method Signature
+When a market resolves, participants can challenge the outcome through the dispute and appeal system.
 
-```ts
-buildLimitSellOptionTx(params: LimitSellOptionTxParams): RawTransaction
-```
+### Opening a Dispute
 
-### Parameters
+If a participant believes the market outcome is incorrect, they can open a dispute.
 
 ```ts
-interface LimitSellOptionTxParams {
-  marketContractAddress: `0x${string}`; // Market contract address
-  selectedOption: number;               // Option index
-  pricePerShare: number;                // Limit price per share (between 0 and 1)
-  sharesAmountWei: bigint;              // Number of shares to sell (in wei)
-  tokenDecimals?: number;               // Token decimals (default: 6)
+const disputeTxs = await rain.buildCreateDisputeTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
+
+for (const tx of disputeTxs) {
+  await yourProvider.sendTransaction(tx);
 }
 ```
 
-### Validations
-
-| Field                   | Type          | Required | Description                                 |
-| ----------------------- | ------------- | -------- | ------------------------------------------- |
-| `marketContractAddress` | `0x${string}` | ✅        | Address of the market contract              |
-| `selectedOption`        | `number`      | ✅        | Option index to place the sell order for    |
-| `pricePerShare`         | `number`      | ✅        | Limit price per share (between `0` and `1`) |
-| `sharesAmountWei`       | `bigint`      | ✅        | Number of shares to sell (must be `> 0`)    |
-| `tokenDecimals`         | `number`      | ❌        | Token decimals (default: `6`)               |
+### Filing an Appeal
 
-### Return Type
+If the dispute resolution is also contested, participants can escalate it through an appeal.
 
 ```ts
-interface RawTransaction {
-  to: `0x${string}`;
-  data: `0x${string}`;
+const appealTxs = await rain.buildCreateAppealTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
+
+for (const tx of appealTxs) {
+  await yourProvider.sendTransaction(tx);
 }
 ```
 
-### Example
+### Extending the Dispute Window
+
+If more time is needed for resolution, the dispute window can be extended.
 
 ```ts
-rain.buildLimitSellOptionTx({
-  marketContractAddress: "0xMarketContractAddress...",
-  selectedOption: 0,
-  pricePerShare: 0.4,
-  sharesAmountWei: 500000n,
+const extendTx = await rain.buildExtendTimeTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
 });
+
+await yourProvider.sendTransaction(extendTx);
 ```
 
 ---
 
-## buildCancelOrdersTx
+## Account Abstraction
 
-Builds **raw EVM transactions** to cancel specific open orders on a Rain market.
+Remove gas fees from your trading experience using stateful execution.
 
-Groups orders by type and returns up to two transactions — one for sell orders (`cancelSellOrders`) and one for buy orders (`cancelBuyOrders`).
+The SDK splits its functionality into two classes. While the `Rain` class is stateless and handles your queries and transaction building, it does not send transactions.
 
-This function **does not send the transaction** — it only prepares calldata.
+To execute trades without requiring users to hold native ETH for gas, you use the `RainAA` class. This stateful class manages Alchemy smart accounts with gas sponsorship.
 
-### Method Signature
+### Setting Up the Execution Engine
 
-```ts
-buildCancelOrdersTx(params: CancelOrdersTxParams): RawTransaction[]
-```
-
-### Parameters
+To get started, you initialize the `RainAA` class with your standard viem wallet client and your Alchemy credentials.
 
 ```ts
-interface OrderToCancel {
-  orderType: 'buy' | 'sell';
-  option: bigint;        // Option index (e.g. 0n for Yes, 1n for No)
-  pricePerShare: bigint; // Price in 18-decimal wei
-  orderId: bigint;       // externalID from the open order
-}
+import { RainAA } from '@rainprotocolsdk/sdk';
+import { arbitrum } from 'viem/chains';
 
-interface CancelOrdersTxParams {
-  marketContractAddress: `0x${string}`;
-  orders: OrderToCancel[];
-}
+const rainAA = new RainAA({
+  walletClient: yourWalletClient,      // viem WalletClient
+  alchemyApiKey: 'your-alchemy-key',
+  paymasterPolicyId: 'your-policy-id',
+  chain: arbitrum,
+  rpcUrl: 'https://...',               // Optional
+});
 ```
 
-### Validations
-
-| Field                   | Type             | Required | Description                           |
-| ----------------------- | ---------------- | -------- | ------------------------------------- |
-| `marketContractAddress` | `0x${string}`    | ✅        | Address of the market contract        |
-| `orders`                | `OrderToCancel[]`| ✅        | Non-empty array of orders to cancel   |
-
-### Return Type
+Once initialized, you connect the client. This derives a smart account from the user's Externally Owned Account (EOA).
 
 ```ts
-RawTransaction[] // 1 tx if only buy or only sell; 2 txs if both
+// Connect, derives smart account from EOA
+const smartAccountAddress = await rainAA.connect();
+console.log('Smart account:', smartAccountAddress);
 ```
 
-### Example
+### Session Management
+
+The `RainAA` class provides simple accessors to retrieve the connected smart account address and the underlying AA client. When the session is over, you can disconnect the user.
 
 ```ts
-const txs = rain.buildCancelOrdersTx({
-  marketContractAddress: "0xMarketContractAddress...",
-  orders: [
-    {
-      orderType: "buy",
-      option: 0n,
-      pricePerShare: 600000000000000000n, // 0.6 in 18 decimals
-      orderId: 42n,
-    },
-    {
-      orderType: "sell",
-      option: 1n,
-      pricePerShare: 400000000000000000n,
-      orderId: 43n,
-    },
-  ],
-});
+rainAA.address;   // Smart account address (throws if not connected)
+rainAA.client;    // Underlying AA client (throws if not connected)
+
+// Disconnect
+rainAA.disconnect();
 ```
 
 ---
 
-## buildCancelAllOpenOrdersTx
+## WebSockets & Live Data
 
-Fetches all open orders for a wallet on a given market from the Rain backend and builds the cancel transactions automatically.
+Keep your application in sync with the protocol without constantly polling for updates.
 
-Returns an empty array if no open orders exist.
+The `RainSocket` class provides a dedicated WebSocket client that connects to the Rain API and exposes typed event subscriptions. Each subscription method returns an unsubscribe function — call it when the user navigates away to prevent memory leaks.
 
-### Method Signature
+### Setting Up
 
 ```ts
-buildCancelAllOpenOrdersTx(params: CancelAllOpenOrdersTxParams): Promise<RawTransaction[]>
-```
+import { RainSocket } from '@rainprotocolsdk/sdk';
 
-### Parameters
+const rs = new RainSocket({ environment: 'production' });
 
-```ts
-interface CancelAllOpenOrdersTxParams {
-  marketId: string;                      // MongoDB _id of the market
-  marketContractAddress: `0x${string}`; // Market contract address
-  walletAddress: `0x${string}`;         // User's wallet address
-  accessToken: string;                   // JWT from Rain auth (login)
-}
+rs.onConnect(() => console.log('Connected'));
+rs.onDisconnect(() => console.log('Disconnected'));
 ```
 
-### Validations
+### Trade Events
+
+```ts
+// Fires when a user buys into a market option
+const unsub = rs.onEnterOption(marketId, (data) => {
+  console.log(data.poolId, data.investments, data.totalInvestmentWei);
+});
 
-| Field                   | Type          | Required | Description                          |
-| ----------------------- | ------------- | -------- | ------------------------------------ |
-| `marketId`              | `string`      | ✅        | MongoDB `_id` from market data       |
-| `marketContractAddress` | `0x${string}` | ✅        | Market contract address              |
-| `walletAddress`         | `0x${string}` | ✅        | Wallet address of the user           |
-| `accessToken`           | `string`      | ✅        | JWT returned from `login()`          |
+// Fires when a new limit order is placed
+const unsub = rs.onOrderCreated(marketId, (data) => {
+  console.log(data.poolId, data.order);
+});
 
-### Return Type
+// Fires when an open order is cancelled
+const unsub = rs.onOrderCancelled(marketId, (data) => {
+  console.log(data.poolId, data.order);
+});
 
-```ts
-RawTransaction[] // empty array if no open orders found
+// Fires when a limit order is partially or fully filled
+const unsub = rs.onOrderFilled(marketId, (data) => {
+  console.log(data.poolId, data.raw);
+});
 ```
 
-### Example
+### Dispute & Appeal Events
 
 ```ts
-const txs = await rain.buildCancelAllOpenOrdersTx({
-  marketId: "698c8f116e985bbfacc7fc01",
-  marketContractAddress: "0xMarketContractAddress...",
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  accessToken: "eyJhbGciOi...",
+// Fires when a dispute is opened on a market
+const unsub = rs.onDisputeOpened(marketId, (data) => {
+  console.log(data.poolId, data.isDisputed, data.status);
 });
-```
 
----
+// Fires when an appeal is filed
+const unsub = rs.onAppealOpened(marketId, (data) => {
+  console.log(data.poolId, data.isAppealed);
+});
 
-## buildCreateMarketTx
+// Fires when the dispute window is extended
+const unsub = rs.onDisputeTimeExtended(marketId, (data) => {
+  console.log(data.poolId, data.newEndTime);
+});
+```
 
-Builds a **raw EVM transaction** for creating a market in Rain Protocol.
+### Resolution Events
 
-This function **does not send the transaction** — it only prepares calldata.
+```ts
+// Fires when a dispute winner is decided
+const unsub = rs.onDisputeWinner(marketId, (data) => {
+  console.log(data.poolId, data.winnerOption);
+});
 
-### Method Signature
+// Fires when an appeal winner is finalized
+const unsub = rs.onAppealWinner(marketId, (data) => {
+  console.log(data.poolId, data.winnerFinalized);
+});
 
-```ts
-buildCreateMarketTx(params: CreateMarketTxParams): Promise<RawTransaction[]>
+// Fires when a user's reward claim is confirmed
+// Note: requires both marketId and userId
+const unsub = rs.onClaimReward(marketId, userId, (data) => {
+  console.log(data.poolId, data.userId);
+});
 ```
 
-### Parameters
+### Cleanup
 
 ```ts
-interface CreateMarketTxParams {
-  marketQuestion: string;
-  marketOptions: string[];
-  marketTags: string[];
-  marketDescription: string;
-  isPublic: boolean;
-  isPublicPoolResolverAi: boolean;
-  creator: `0x${string}`;
-  startTime: bigint;         // Unix timestamp (seconds)
-  endTime: bigint;           // Must be > startTime
-  no_of_options: bigint;     // Number of options (>= 2)
-  inputAmountWei: bigint;    // Initial liquidity (token wei)
-  barValues: number[];       // Token distribution per option in %
-  baseToken: `0x${string}`; // ERC20 token address
-  tokenDecimals?: number;    // Optional (default: 6)
-}
+// Stop a specific subscription
+unsub();
+
+// Disconnect the socket entirely
+rs.disconnect();
 ```
 
-### Validations
+---
 
-| Field                    | Type               | Required | Description                                |
-| ------------------------ | ------------------ | -------- | ------------------------------------------ |
-| `marketQuestion`         | `string`           | ✅        | Market question (cannot be empty)          |
-| `marketOptions`          | `string[]`         | ✅        | List of options (2 to 26)                  |
-| `marketTags`             | `string[]`         | ✅        | Tags related to the market (1 to 3)        |
-| `marketDescription`      | `string`           | ✅        | Detailed market description                |
-| `isPublic`               | `boolean`          | ✅        | Whether market is public                   |
-| `isPublicPoolResolverAi` | `boolean`          | ✅        | AI resolver flag                           |
-| `creator`                | `0x${string}`      | ✅        | Market creator address                     |
-| `startTime`              | `bigint`           | ✅        | Market start timestamp                     |
-| `endTime`                | `bigint`           | ✅        | Must be greater than `startTime`           |
-| `no_of_options`          | `bigint`           | ✅        | Number of market options (>= 2)            |
-| `inputAmountWei`         | `bigint`           | ✅        | Initial liquidity (minimum 10 tokens)      |
-| `barValues`              | `number[]`         | ✅        | Cannot be empty                            |
-| `baseToken`              | `0x${string}`      | ✅        | ERC20 base token address                   |
-| `tokenDecimals`          | `number`           | ❌        | Defaults to `6`                            |
+## Environments & Configuration
 
-### Minimum Liquidity Rule
+Set up your application for development, testing, or production.
 
-#### inputAmountWei >= 10 tokens
+When initializing the Rain class, your configuration dictates which endpoints and contract addresses the SDK interacts with.
 
-### Return Type
+### Environment Addresses
 
-```ts
-RawTransaction[] // [approve, createMarket] or [createMarket] depending on allowance
-```
+The SDK automatically selects the correct Factory Address and API endpoint based on your chosen environment.
 
-### Note
+| Environment | API Endpoint | Factory Address |
+| ----------- | ------------ | --------------- |
+| development | dev-api.rain.one | 0x148DA7F2039B2B00633AC2ab566f59C8a4C86313 |
+| stage | stg-api.rain.one | 0x6109c9f28FE3Ad84c51368f7Ef2d487ca020c561 |
+| production | prod-api.rain.one | 0xccCB3C03D9355B01883779EF15C1Be09cf3623F1 |
 
-If the user has not approved the **Rain Factory contract**, the function will return two transactions **(approve + create market)**, but if approval already exists, it will return only one transaction **(create market)**.
+You will also frequently interact with the standard base token, which is Arbitrum USDT (`0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9`) using 6 decimals.
 
-### Example
+### Full Configuration Options
 
 ```ts
-const txs = await rain.buildCreateMarketTx({
-  marketQuestion: "Will BTC hit 100k?",
-  marketOptions: ["Yes", "No"],
-  marketTags: ["crypto", "bitcoin"],
-  marketDescription: "Prediction market for BTC price",
-  isPublic: true,
-  isPublicPoolResolverAi: false,
-  creator: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  startTime: 1770836400n,
-  endTime: 1770922800n,
-  no_of_options: 2n,
-  inputAmountWei: 100000000n,
-  barValues: [50, 50],
-  baseToken: "0xCa4f77A38d8552Dd1D5E44e890173921B67725F4",
+const rain = new Rain({
+  environment: 'development',  // 'development' | 'stage' | 'production'
+  rpcUrl: 'https://...',       // Optional, defaults to public Arbitrum RPCs
 });
 ```
 
 ---
 
-## buildClaimTx
+## API Reference
 
-Builds a **raw EVM transaction** to claim funds from a resolved Rain market.
+A comprehensive list of methods, parameters, and return types for the Rain SDK.
 
-This function **does not send the transaction** — it only prepares calldata.
+All transaction builders return an unsigned `RawTransaction` (`{ to, data, value? }`) that must be executed by a wallet or smart account.
 
-### Method Signature
+---
 
-```ts
-buildClaimTx(params: ClaimTxParams): Promise<RawTransaction>
-```
+### Authentication
+
+#### `login(params)`
 
-### Parameters
+Authenticate a user with the Rain API.
 
 ```ts
-interface ClaimTxParams {
-  marketId: string;
-  walletAddress: `0x${string}`;
-}
+const result = await rain.login({
+  walletAddress: '0x...',
+  signature: '0x...',
+});
+// Returns: LoginResult
+// { accessToken, userId, ... }
 ```
 
-### Validations
-
-| Parameter       | Type          | Required | Description                        |
-| --------------- | ------------- | -------- | ---------------------------------- |
-| `marketId`      | `string`      | ✅        | Unique identifier of the market    |
-| `walletAddress` | `0x${string}` | ✅        | Address of the user claiming funds |
+---
 
-### Return Type
+### Market Queries
 
-```ts
-interface RawTransaction {
-  to: `0x${string}`;
-  data: `0x${string}`;
-}
-```
+#### `getPublicMarkets(params)`
 
-### Example
+Browse markets based on specific filters.
 
 ```ts
-const tx = await rain.buildClaimTx({
-  marketId: "698c8f116e985bbfacc7fc01",
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+const markets = await rain.getPublicMarkets({
+  limit: 12,
+  offset: 0,
+  sortBy: 'Liquidity',   // 'Liquidity' | 'Volumn' | 'latest'
+  status: 'Live',        // 'Live' | 'Trading' | 'Closed' | ...
+  creator: '0x...',      // Optional — filter by creator
 });
+// Returns: Market[]
+// { id, title, totalVolume, status, contractAddress, poolOwnerWalletAddress }
 ```
 
----
-
-## buildCloseMarketTx
-
-Builds **raw EVM transactions** to close a Rain market and submit the resolution outcome.
-
-Handles both V2 and V3 market contracts automatically. For V3 markets, checks token allowances and prepends an approval transaction if needed.
+#### `getMarketById(params)`
 
-This function **does not send the transactions** — it only prepares calldata.
-
-### Method Signature
+Fetch a single market by its API ID.
 
 ```ts
-buildCloseMarketTx(params: CloseMarketTxParams): Promise<RawTransaction[]>
+const market = await rain.getMarketById({
+  marketId: '698c8f116e985bbfacc7fc01',
+  accessToken: 'your-access-token',  // Optional
+});
+// Returns: Market
 ```
 
-### Parameters
+#### `getUserInvestments(params)`
+
+Fetch all active investments for a specific user.
 
 ```ts
-interface CloseMarketTxParams {
-  marketId: string;                    // MongoDB _id of the market
-  walletAddress: `0x${string}`;       // Smart account address
-  proposedOutcome?: number;            // Winner option index (required for V2 and V3 manual resolver)
-  usdtTokenAddress?: `0x${string}`;  // Required for V3 USDT markets
-  rainTokenAddress?: `0x${string}`;  // Required for V3 RAIN markets
-  usdtSymbol?: string;                 // USDT symbol for the environment (e.g. "USDTm")
-  tokenDecimals?: number;             // Defaults to 6
-}
+const investments = await rain.getUserInvestments({
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
+// Returns: UserInvestment[]
 ```
 
-### Validations
+---
 
-| Field                | Type          | Required | Description                                              |
-| -------------------- | ------------- | -------- | -------------------------------------------------------- |
-| `marketId`           | `string`      | ✅        | MongoDB `_id` of the market                              |
-| `walletAddress`      | `0x${string}` | ✅        | Smart account used for allowance checks                  |
-| `proposedOutcome`    | `number`      | ⚠️        | Required for V2 markets and V3 manual resolver markets   |
-| `usdtTokenAddress`   | `0x${string}` | ⚠️        | Required for V3 USDT markets                             |
-| `rainTokenAddress`   | `0x${string}` | ⚠️        | Required for V3 RAIN markets                             |
-| `usdtSymbol`         | `string`      | ❌        | Used to detect if market uses USDT as base token         |
-| `tokenDecimals`      | `number`      | ❌        | Defaults to `6`                                          |
+### Transaction Builders
 
-### Return Type
+#### Approvals
 
 ```ts
-RawTransaction[] // [approve?, closePool] for V3 or [closePool, chooseWinner] for V2
+// buildApprovalTx(params) — ERC20 approve
+const tx = rain.buildApprovalTx({
+  tokenAddress: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',  // USDT
+  spender: '0x...',     // market contract address
+  amount: 100_000_000n, // Optional — defaults to max uint256
+});
 ```
 
-### Example
+#### Creating a Market
 
-```ts
-// V2 market
-const txs = await rain.buildCloseMarketTx({
-  marketId: "698c8f116e985bbfacc7fc01",
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  proposedOutcome: 0,
-});
+Returns `[approveTx, createTx]` if approval is needed, or `[createTx]` if already approved.
 
-// V3 manual resolver with RAIN token
-const txs = await rain.buildCloseMarketTx({
-  marketId: "698c8f116e985bbfacc7fc01",
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  proposedOutcome: 1,
-  rainTokenAddress: "0xRainTokenAddress...",
-  usdtSymbol: "USDTm",
+```ts
+const txs = await rain.buildCreateMarketTx({
+  marketQuestion: 'Will BTC hit 100k?',
+  marketOptions: ['Yes', 'No', 'Maybe'],
+  marketTags: ['crypto', 'bitcoin'],
+  marketDescription: 'Prediction market for BTC price',
+  isPublic: true,
+  isPublicPoolResolverAi: false,
+  creator: '0x996ea23940f4a01610181D04bdB6F862719b63f0',
+  startTime: 1770836400n,
+  endTime: 1770922800n,
+  no_of_options: 3n,
+  inputAmountWei: 100_000_000n,
+  barValues: [34, 33, 33],
+  baseToken: '0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9',
+  tokenDecimals: 6,
 });
 ```
 
----
-
-## buildCreateDisputeTx
+#### Trading Options
 
-Builds **raw EVM transactions** to open a dispute on a Rain market.
+```ts
+// buildBuyOptionRawTx(params) — Market buy
+const tx = rain.buildBuyOptionRawTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1n,           // Option index (bigint)
+  buyAmountInWei: 10_000_000n, // 10 USDT
+});
 
-Checks the user's token allowance against the dispute fee and prepends an approval transaction if needed.
+// buildLimitBuyOptionTx(params) — Limit buy order
+const limitBuyTx = rain.buildLimitBuyOptionTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1,
+  pricePerShare: 500000000000000000n,  // 0.50 in 1e18
+  buyAmountInWei: 10_000_000n,
+  tokenDecimals: 6,
+});
 
-This function **does not send the transactions** — it only prepares calldata.
+// buildLimitSellOptionTx(params) — Limit sell order
+const limitSellTx = rain.buildLimitSellOptionTx({
+  marketContractAddress: '0x...',
+  selectedOption: 1,
+  pricePerShare: 500000000000000000n,  // 0.50 in 1e18
+  shares: 5_000_000n,
+  tokenDecimals: 6,
+});
 
-### Method Signature
+// buildCancelOrdersTx(params) — Cancel specific open orders
+const cancelTx = rain.buildCancelOrdersTx({
+  marketContractAddress: '0x...',
+  orders: [
+    { option: 1, price: 0.5, orderID: 1n },
+    { option: 1, price: 0.6, orderID: 2n },
+  ],
+});
 
-```ts
-buildCreateDisputeTx(params: CreateDisputeTxParams): Promise<RawTransaction[]>
+// buildCancelAllOpenOrdersTx(params) — Cancel all open orders for a user
+const cancelAllTx = await rain.buildCancelAllOpenOrdersTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
 ```
 
-### Parameters
+#### Market Lifecycle
 
 ```ts
-interface CreateDisputeTxParams {
-  marketId: string;                   // MongoDB _id of the market
-  walletAddress: `0x${string}`;      // User's wallet address
-  usdtTokenAddress?: `0x${string}`; // Required for USDT markets
-  rainTokenAddress?: `0x${string}`; // Required for RAIN markets
-  usdtSymbol?: string;                // Used to detect market token type
-}
-```
+// buildCloseMarketTx(params) — Close market and halt trading
+const closeTx = await rain.buildCloseMarketTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
 
-### Validations
+// buildAddLiquidityTx(params) — Add liquidity to a market
+const addLiqTxs = await rain.buildAddLiquidityTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  amount: 100,  // human-readable — reads baseToken() on-chain, uses 6 decimals for USDT or 18 for RAIN
+});
+// Returns [approveTx, enterLiquidityTx] or [enterLiquidityTx] if already approved.
 
-| Field               | Type          | Required | Description                                  |
-| ------------------- | ------------- | -------- | -------------------------------------------- |
-| `marketId`          | `string`      | ✅        | MongoDB `_id` of the market                  |
-| `walletAddress`     | `0x${string}` | ✅        | Address of the user opening the dispute       |
-| `usdtTokenAddress`  | `0x${string}` | ⚠️        | Required if market uses USDT as base token    |
-| `rainTokenAddress`  | `0x${string}` | ⚠️        | Required if market uses RAIN as base token    |
-| `usdtSymbol`        | `string`      | ❌        | Used to detect if market uses USDT            |
+// buildClaimTx(params) — Claim winnings after market settles
+const claimTx = await rain.buildClaimTx({
+  marketId: '698c8f116e985bbfacc7fc01',
+  walletAddress: '0x996ea23940f4a01610181D04bdB6F862719b63f0',
+});
+```
 
-### Return Type
+#### Disputes & Appeals
 
 ```ts
-RawTransaction[] // [approve?, openDispute]
-```
+// buildCreateDisputeTx(params) — Open a dispute on market outcome
+const disputeTxs = await rain.buildCreateDisputeTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
 
-### Example
+// buildCreateAppealTx(params) — Appeal a dispute decision
+const appealTxs = await rain.buildCreateAppealTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
+});
 
-```ts
-const txs = await rain.buildCreateDisputeTx({
-  marketId: "698c8f116e985bbfacc7fc01",
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  rainTokenAddress: "0xRainTokenAddress...",
-  usdtSymbol: "USDTm",
+// buildExtendTimeTx(params) — Extend the dispute resolution window
+const extendTx = await rain.buildExtendTimeTx({
+  marketContractAddress: '0x...',
+  walletAddress: '0x...',
+  accessToken: 'your-access-token',
 });
 ```
 
 ---
 
-## buildCreateAppealTx
+### RainSocket — WebSocket Subscriptions
 
-Builds **raw EVM transactions** to appeal a dispute resolution on a Rain market.
-
-Identical flow to `buildCreateDisputeTx` — checks token allowance against the appeal fee and prepends an approval if needed.
-
-This function **does not send the transactions** — it only prepares calldata.
-
-### Method Signature
+All subscription methods return an unsubscribe function `() => void`.
 
 ```ts
-buildCreateAppealTx(params: CreateAppealTxParams): Promise<RawTransaction[]>
-```
+import { RainSocket } from '@rainprotocolsdk/sdk';
 
-### Parameters
+const rs = new RainSocket({ environment: 'production' });
 
-```ts
-interface CreateAppealTxParams {
-  marketId: string;                   // MongoDB _id of the market
-  walletAddress: `0x${string}`;      // User's wallet address
-  usdtTokenAddress?: `0x${string}`; // Required for USDT markets
-  rainTokenAddress?: `0x${string}`; // Required for RAIN markets
-  usdtSymbol?: string;                // Used to detect market token type
-}
-```
+// Connection lifecycle
+rs.onConnect(callback)
+rs.onDisconnect(callback)
 
-### Validations
+// Trade events
+rs.onEnterOption(marketId, callback)       // enter-option/{marketId}
+rs.onOrderCreated(marketId, callback)      // order-created/{marketId}
+rs.onOrderCancelled(marketId, callback)    // order-cancelled/{marketId}
+rs.onOrderFilled(marketId, callback)       // order-filled/{marketId}
 
-| Field               | Type          | Required | Description                                  |
-| ------------------- | ------------- | -------- | -------------------------------------------- |
-| `marketId`          | `string`      | ✅        | MongoDB `_id` of the market                  |
-| `walletAddress`     | `0x${string}` | ✅        | Address of the user filing the appeal         |
-| `usdtTokenAddress`  | `0x${string}` | ⚠️        | Required if market uses USDT as base token    |
-| `rainTokenAddress`  | `0x${string}` | ⚠️        | Required if market uses RAIN as base token    |
-| `usdtSymbol`        | `string`      | ❌        | Used to detect if market uses USDT            |
+// Dispute & appeal events
+rs.onDisputeOpened(marketId, callback)         // dispute-opened/{marketId}
+rs.onAppealOpened(marketId, callback)          // appeal-opened/{marketId}
+rs.onDisputeTimeExtended(marketId, callback)   // dispute-time-extented/{marketId}
 
-### Return Type
+// Resolution events
+rs.onDisputeWinner(marketId, callback)                 // dispute-winner/{marketId}
+rs.onAppealWinner(marketId, callback)                  // appeal-winner/{marketId}
+rs.onClaimReward(marketId, userId, callback)           // claim-reward/{marketId}/{userId}
 
-```ts
-RawTransaction[] // [approve?, openDispute]
-```
-
-### Example
-
-```ts
-const txs = await rain.buildCreateAppealTx({
-  marketId: "698c8f116e985bbfacc7fc01",
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  rainTokenAddress: "0xRainTokenAddress...",
-  usdtSymbol: "USDTm",
-});
+// Disconnect
+rs.disconnect()
 ```
 
 ---
 
-## buildExtendTimeTx
+### RainAA — Account Abstraction
 
-Builds a **raw EVM transaction** to re-submit an appeal by extending the oracle voting timer on a disputed Rain market.
+`RainAA` manages Alchemy smart accounts with gas sponsorship.
 
-Internally calls `resolver()` on the market contract to resolve the oracle address, then fetches a signed epoch from the Rain backend, and encodes the `extendTime(epoch, signature)` call targeting the oracle contract.
+```ts
+import { RainAA } from '@rainprotocolsdk/sdk';
+import { arbitrum } from 'viem/chains';
 
-This function **does not send the transaction** — it only prepares calldata.
+const rainAA = new RainAA({
+  walletClient: yourWalletClient,       // viem WalletClient
+  alchemyApiKey: 'your-alchemy-key',
+  paymasterPolicyId: 'your-policy-id',
+  chain: arbitrum,
+  rpcUrl: 'https://...',               // Optional
+});
 
-### Method Signature
+// Connect — derives smart account from EOA
+const smartAccountAddress = await rainAA.connect();
 
-```ts
-buildExtendTimeTx(params: ExtendTimeTxParams): Promise<RawTransaction>
-```
+// Accessors
+rainAA.address;   // Smart account address (throws if not connected)
+rainAA.client;    // Underlying AA client (throws if not connected)
 
-### Parameters
-
-```ts
-interface ExtendTimeTxParams {
-  marketContractAddress: `0x${string}`; // TradeMarket contract address — resolver() is called on it
-  walletAddress: `0x${string}`;         // Smart account address
-  accessToken: string;                   // JWT from Rain auth (login)
-}
+// Disconnect
+rainAA.disconnect();
 ```
 
-### Validations
-
-| Field                   | Type          | Required | Description                                          |
-| ----------------------- | ------------- | -------- | ---------------------------------------------------- |
-| `marketContractAddress` | `0x${string}` | ✅        | Market contract — used to look up the oracle address |
-| `walletAddress`         | `0x${string}` | ✅        | Smart account address of the caller                  |
-| `accessToken`           | `string`      | ✅        | JWT returned from `login()`                          |
+---
 
-### Return Type
+### Key Types
 
 ```ts
+// Core transaction type — returned by all builders
 interface RawTransaction {
-  to: `0x${string}`; // oracle contract address (resolved on-chain)
+  to: `0x${string}`;
   data: `0x${string}`;
+  value?: bigint;
 }
-```
 
-### Example
+// Market from listing endpoint
+interface Market {
+  id: string;
+  title: string;
+  totalVolume: string;
+  status: MarketStatus;
+  contractAddress?: string;
+  poolOwnerWalletAddress?: string;
+}
 
-```ts
-const tx = await rain.buildExtendTimeTx({
-  marketContractAddress: "0xMarketContractAddress...",
-  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-  accessToken: "eyJhbGciOi...",
-});
+type MarketStatus = 'Live' | 'New' | 'WaitingForResult' | 'UnderDispute' |
+  'UnderAppeal' | 'ClosingSoon' | 'InReview' | 'InEvaluation' | 'Closed' | 'Trading';
 ```
 
 ---
 
-## RainAA Class (Account Abstraction)
+## Full Method Reference
+
+A complete directory of all available methods in the Rain SDK.
+
+### Rain Class
+
+| Method | Returns | Async |
+| ------ | ------- | ----- |
+| **Authentication** | | |
+| `login(params)` | `LoginResult` | Yes |
+| **Market Queries** | | |
+| `getPublicMarkets(params)` | `Market[]` | Yes |
+| `getMarketById(params)` | `Market` | Yes |
+| `getUserInvestments(params)` | `UserInvestment[]` | Yes |
+| **Transaction Builders** | | |
+| `buildApprovalTx(params)` | `RawTransaction` | No |
+| `buildCreateMarketTx(params)` | `RawTransaction[]` | Yes |
+| `buildBuyOptionRawTx(params)` | `RawTransaction` | No |
+| `buildLimitBuyOptionTx(params)` | `RawTransaction` | No |
+| `buildLimitSellOptionTx(params)` | `RawTransaction` | No |
+| `buildCancelOrdersTx(params)` | `RawTransaction[]` | No |
+| `buildCancelAllOpenOrdersTx(params)` | `RawTransaction[]` | Yes |
+| `buildAddLiquidityTx(params)` | `RawTransaction[]` | Yes |
+| `buildClaimTx(params)` | `RawTransaction` | Yes |
+| `buildCloseMarketTx(params)` | `RawTransaction[]` | Yes |
+| `buildCreateDisputeTx(params)` | `RawTransaction[]` | Yes |
+| `buildCreateAppealTx(params)` | `RawTransaction[]` | Yes |
+| `buildExtendTimeTx(params)` | `RawTransaction` | Yes |
+
+### RainAA Class
+
+| Method | Returns | Async |
+| ------ | ------- | ----- |
+| `connect()` | `` 0x${string} `` | Yes |
+| `disconnect()` | `void` | No |
+| `.address` | `` 0x${string} `` | — |
+| `.client` | Smart wallet client | — |
+
+### RainSocket Class
+
+| Method | Returns | Async |
+| ------ | ------- | ----- |
+| `onConnect(callback)` | `void` | No |
+| `onDisconnect(callback)` | `void` | No |
+| `onEnterOption(marketId, callback)` | `Unsubscribe` | No |
+| `onOrderCreated(marketId, callback)` | `Unsubscribe` | No |
+| `onOrderCancelled(marketId, callback)` | `Unsubscribe` | No |
+| `onOrderFilled(marketId, callback)` | `Unsubscribe` | No |
+| `onDisputeOpened(marketId, callback)` | `Unsubscribe` | No |
+| `onAppealOpened(marketId, callback)` | `Unsubscribe` | No |
+| `onDisputeTimeExtended(marketId, callback)` | `Unsubscribe` | No |
+| `onDisputeWinner(marketId, callback)` | `Unsubscribe` | No |
+| `onAppealWinner(marketId, callback)` | `Unsubscribe` | No |
+| `onClaimReward(marketId, userId, callback)` | `Unsubscribe` | No |
+| `disconnect()` | `void` | No |
 
-`RainAA` is responsible for:
+---
 
-* Smart account creation
-* Session management (coming soon)
-* Gas-sponsored execution (coming soon)
-* Transaction submission (coming soon)
+## Local Development
 
-> `RainAA` consumes raw transactions generated by `Rain`.
+Instructions for building and testing the Rain SDK locally.
 
-### Conceptual Flow
+If you are looking to contribute to the SDK or run the test suite, follow these steps to set up your local development environment.
 
-```ts
-Rain (WHAT to do)
-   ↓
-Raw Transaction
-   ↓
-RainAA (HOW to execute)
+### Installation
+
+First, navigate to the rain-sdk directory and install the necessary dependencies:
+
+```bash
+cd rain-sdk
+npm install
 ```
 
----
+### Available Scripts
 
-## Versioning Policy
+The following commands are available for development and testing.
 
-Rain SDK follows **Semantic Versioning**:
+#### Build the SDK
 
-* **Patch** (`1.0.x`) → Bug fixes
-* **Minor** (`1.x.0`) → New features, backward compatible
-* **Major** (`x.0.0`) → Breaking API changes
+Compiles the TypeScript source code into the final distribution files.
 
----
+```bash
+npm run build
+```
 
-## Recommended Usage Pattern
+#### Development Mode
 
-```ts
-// 1. Init SDK
-const rain = new Rain({ environment: "production" });
+Runs the development environment in watch mode, automatically recompiling when files are changed.
 
-// 2. Login
-const { accessToken } = await rain.login({ signature, walletAddress, smartWalletAddress });
+```bash
+npm run dev
+```
 
-// 3. Read data / build tx
-const rawTx = await rain.buildBuyOptionRawTx({ ... });
+#### Run Tests
 
-// 4. Execute via your provider
-await yourProvider.sendTransaction(rawTx);
+Executes the standard test suite to ensure everything is functioning correctly.
+
+```bash
+npm test
 ```
 
----
+#### Integration Tests
+
+Runs tests that interact with external services or the blockchain to verify end-to-end functionality.
 
-**Rain SDK** is built to scale with both products and protocols.
+```bash
+npm run test:integration
+```