@rainprotocolsdk/sdk 1.2.0 → 2.0.0

package/README.md

@@ -30,10 +30,68 @@ yarn add @rainprotocolsdk/sdk
 ```ts
 import { Rain } from "@rainprotocolsdk/sdk";
 
-const rain = new Rain();
+const rain = new Rain({ environment: "production" });
 ```
 
-> The constructor is intentionally empty to allow future configuration without breaking changes.
+### Constructor Parameters
+
+```ts
+interface RainCoreConfig {
+  environment?: "development" | "stage" | "production"; // default: "development"
+  rpcUrl?: string; // optional custom RPC URL
+}
+```
+
+---
+
+## login
+
+Authenticates a user against the Rain backend using a wallet signature and returns a JWT access token.
+
+The caller is responsible for signing the message — pass the resulting signature along with the wallet addresses.
+
+### Method Signature
+
+```ts
+login(params: LoginParams): Promise<LoginResult>
+```
+
+### Parameters
+
+```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
+
+```ts
+interface LoginResult {
+  accessToken: string; // JWT token for authenticated API calls
+  userId: string;      // Backend user ID
+}
+```
+
+### Example
+
+```ts
+// 1. Sign the message with your wallet provider
+const signature = await walletClient.signMessage({
+  message: walletAddress.toLowerCase(),
+});
+
+// 2. Login
+const { accessToken, userId } = await rain.login({
+  signature,
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+  smartWalletAddress: "0xSmartAccountAddress...",
+  referredBy: "REFCODE123", // optional
+});
+```
 
 ---
 
@@ -51,8 +109,8 @@ getPublicMarkets(params: GetMarketsParams): Promise<Market[]>;
 
 ```ts
 interface GetMarketsParams {
-  limit: number;
-  offset: number;
+  limit?: number;
+  offset?: number;
   sortBy?: "Liquidity" | "Volumn" | "latest";
   status?: 'Live' | 'New' | 'WaitingForResult' | 'UnderDispute' | 'UnderAppeal' | 'ClosingSoon' | 'InReview' | 'InEvaluation' | 'Closed' | 'Trading';
 }
@@ -62,95 +120,102 @@ interface GetMarketsParams {
 
 ```ts
 const markets = await rain.getPublicMarkets({
-  limit?: 12,
-  offset?: 1,
-  sortBy?: "Liquidity",
-  status?: "Live",
+  limit: 12,
+  offset: 1,
+  sortBy: "Liquidity",
+  status: "Live",
 });
 ```
 
 ---
 
-## buildApprovalTx
+## getMarketById
 
-```
-Builds a raw ERC20 approval transaction if needed.
+Fetches a single market by its ID from the Rain backend.
 
-This function prepares an unsigned approve(spender, amount) transaction and does not execute it.
+### Method Signature
 
-If amount is not provided, a default large allowance is approved.
+```ts
+getMarketById(params: GetMarketByIdParams): Promise<Market>
 ```
 
-### Return Type
+### Parameters
 
 ```ts
-interface RawTransaction {
-  to: `0x${string}`;
-  data: `0x${string}`;
+interface GetMarketByIdParams {
+  marketId: string; // MongoDB _id of the market
 }
 ```
 
+### Validations
+
+| Parameter  | Type     | Required | Description            |
+| ---------- | -------- | -------- | ---------------------- |
+| `marketId` | `string` | ✅        | Unique market `_id`    |
+
 ### Example
 
 ```ts
-const approvalTx = rain.buildApprovalTx({ 
-  tokenAddress: `0x${string}`, // Approval token address 
-  spender: `0x${string}`,  // Market contract address
-  amount?: 1000000000000000000n // optional parameter
-   });
+const market = await rain.getMarketById({
+  marketId: "698c8f116e985bbfacc7fc01",
+});
 ```
 
 ---
 
-## buildCreateMarketTx
-
-Builds a **raw EVM transaction** for creating a market in rain protocol.
+## getUserInvestments
 
-This function **does not send the transaction** — it only prepares calldata.
+Fetches a user's invested markets from the Rain backend. Requires a valid access token.
 
 ### Method Signature
 
 ```ts
-buildCreateMarketTx(params: CreateMarketTxParams): RawTransaction;
+getUserInvestments(params: GetUserInvestmentsParams): Promise<UserInvestment[]>
 ```
 
 ### Parameters
 
 ```ts
-interface CreateMarketTxParams {
-  isPublic: boolean;
-  isPublicPoolResolverAi: boolean;
-  creator: `0x${string}`;
-  startTime: number | bigint;        // Unix timestamp (seconds)
-  endTime: number | bigint;          // Must be > startTime
-  options: number;                   // Number of options (> 0)
-  ipfsUrl: string;                   // IPFS CID
-  inputAmountWei: bigint;            // Initial liquidity (token wei)
-  barValues: (number)[];             // Token Distribution values in options in %
-  baseToken: `0x${string}`;          // ERC20 token address
-  tokenDecimals?: number;            // Optional (default: 6)
+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';
 }
 ```
 
 ### Validations
 
-| Field                    | Type               | Required | Description                      |
-| ------------------------ | ------------------ | -------- | -------------------------------- |
-| `isPublic`               | `boolean`          | ✅        | Whether market is public         |
-| `isPublicPoolResolverAi` | `boolean`          | ✅        | AI resolver flag                 |
-| `creator`                | `0x${string}`      | ✅        | Market creator address           |
-| `startTime`              | `number \| bigint` | ✅        | Market start timestamp           |
-| `endTime`                | `number \| bigint` | ✅        | Must be greater than `startTime` |
-| `options`                | `number`           | ✅        | Number of market options (> 2)   |
-| `ipfsUrl`                | `string`           | ✅        | IPFS CID containing metadata     |
-| `inputAmountWei`         | `bigint`           | ✅        | Initial liquidity amount         |
-| `barValues`              | `array`            | ✅        | Cannot be empty                  |
-| `baseToken`              | `0x${string}`      | ✅        | ERC20 base token address         |
-| `tokenDecimals`          | `number`           | ❌        | Defaults to `6`                  |
+| 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              |
 
-### Minimum Liquidity Rule
+### Example
+
+```ts
+const investments = await rain.getUserInvestments({
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+  accessToken: "eyJhbGciOi...",
+  limit: 10,
+  offset: 1,
+  status: "Live",
+});
+```
+
+---
+
+## buildApprovalTx
+
+Builds a raw ERC20 approval transaction if needed.
+
+This function prepares an unsigned `approve(spender, amount)` transaction and does not execute it.
 
-# inputAmountWei >= 10 tokens
+If `amount` is not provided, a default large allowance is approved.
 
 ### Return Type
 
@@ -164,28 +229,11 @@ interface RawTransaction {
 ### Example
 
 ```ts
-rain.buildCreateMarketTx({
-    isPublic: true,
-    isPublicPoolResolverAi: false,
-    creator: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
-    startTime: 1770836400,
-    endTime: 1770922800,
-    options: 3,
-    ipfsUrl: "QmUdu2eLEQ2qFtNeVVLfVQDBCoc4DT5752enxDitLGmVec",
-    inputAmountWei: 100000000n,
-    barValues: [48, 40, 1],
-    baseToken: "0xCa4f77A38d8552Dd1D5E44e890173921B67725F4"
-  })
-```
-
-### Recommended Execution Pattern
-
-```ts
-// 1. Build raw transaction
-const rawTx = rain.buildCreateMarketTx({...});
-
-// 2. Execute using your provider
-await yourProvider.sendTransaction(rawTx);
+const approvalTx = rain.buildApprovalTx({
+  tokenAddress: "0xTokenAddress...",  // ERC20 token address
+  spender: "0xMarketContractAddress...", // Market contract address
+  amount: 1000000000000000000n // optional
+});
 ```
 
 ---
@@ -206,9 +254,9 @@ buildBuyOptionRawTx(params: EnterOptionTxParams): RawTransaction;
 
 ```ts
 interface EnterOptionTxParams {
-  address: `0x${string}`;        // Trademarket contract address
-  selectedOption: number;       // Option index
-  buyInWei: bigint;              // Amount in wei
+  marketContractAddress: `0x${string}`; // TradeMarket contract address
+  selectedOption: bigint;               // Option index
+  buyAmountInWei: bigint;               // Amount in wei
 }
 ```
 
@@ -225,11 +273,12 @@ interface RawTransaction {
 
 ```ts
 const rawTx = rain.buildBuyOptionRawTx({
-  address: `0x${string}`,
-  selectedOption: 1,
-  buyInWei: 1000000000000000000n,
+  marketContractAddress: "0xMarketContractAddress...",
+  selectedOption: 1n,
+  buyAmountInWei: 1000000n,
 });
 ```
+
 ---
 
 ## buildLimitBuyOptionTx
@@ -248,22 +297,23 @@ buildLimitBuyOptionTx(params: EnterLimitOptionTxParams): RawTransaction
 
 ```ts
 interface EnterLimitOptionTxParams {
-    marketContractAddress: `0x${string}`; // market contract address
-    selectedOption: number; // Option index
-    pricePerShare: bigint; // price per share
-    buyAmountInWei: bigint; // total buy amount (already converted to token wei)
-    tokenDecimals?: number; // token decimals optional (default: `6`)
+  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)
 }
 ```
+
 ### Validations
 
 | Field                   | Type          | Required | Description                                            |
 | ----------------------- | ------------- | -------- | ------------------------------------------------------ |
-| `marketContractAddress` | `0x${string}` | ✅        | Address of the market contract             |
+| `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 optional (default: `6`)                          |
+| `tokenDecimals`         | `number`      | ❌        | Token decimals (default: `6`)                          |
 
 ### Return Type
 
@@ -278,11 +328,499 @@ interface RawTransaction {
 
 ```ts
 rain.buildLimitBuyOptionTx({
-    marketContractAddress: `0x${string}`,
-    buyAmountInWei: 1000000,
-    pricePerShare: 0.1,
-    selectedOption: 1,
-  })
+  marketContractAddress: "0xMarketContractAddress...",
+  selectedOption: 1,
+  pricePerShare: 0.6,
+  buyAmountInWei: 1000000n,
+});
+```
+
+---
+
+## buildLimitSellOptionTx
+
+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.
+
+### Method Signature
+
+```ts
+buildLimitSellOptionTx(params: LimitSellOptionTxParams): RawTransaction
+```
+
+### Parameters
+
+```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)
+}
+```
+
+### 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`)               |
+
+### Return Type
+
+```ts
+interface RawTransaction {
+  to: `0x${string}`;
+  data: `0x${string}`;
+}
+```
+
+### Example
+
+```ts
+rain.buildLimitSellOptionTx({
+  marketContractAddress: "0xMarketContractAddress...",
+  selectedOption: 0,
+  pricePerShare: 0.4,
+  sharesAmountWei: 500000n,
+});
+```
+
+---
+
+## buildCancelOrdersTx
+
+Builds **raw EVM transactions** to cancel specific open orders on a Rain market.
+
+Groups orders by type and returns up to two transactions — one for sell orders (`cancelSellOrders`) and one for buy orders (`cancelBuyOrders`).
+
+This function **does not send the transaction** — it only prepares calldata.
+
+### Method Signature
+
+```ts
+buildCancelOrdersTx(params: CancelOrdersTxParams): RawTransaction[]
+```
+
+### Parameters
+
+```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
+}
+
+interface CancelOrdersTxParams {
+  marketContractAddress: `0x${string}`;
+  orders: OrderToCancel[];
+}
+```
+
+### Validations
+
+| Field                   | Type             | Required | Description                           |
+| ----------------------- | ---------------- | -------- | ------------------------------------- |
+| `marketContractAddress` | `0x${string}`    | ✅        | Address of the market contract        |
+| `orders`                | `OrderToCancel[]`| ✅        | Non-empty array of orders to cancel   |
+
+### Return Type
+
+```ts
+RawTransaction[] // 1 tx if only buy or only sell; 2 txs if both
+```
+
+### Example
+
+```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,
+    },
+  ],
+});
+```
+
+---
+
+## buildCancelAllOpenOrdersTx
+
+Fetches all open orders for a wallet on a given market from the Rain backend and builds the cancel transactions automatically.
+
+Returns an empty array if no open orders exist.
+
+### Method Signature
+
+```ts
+buildCancelAllOpenOrdersTx(params: CancelAllOpenOrdersTxParams): Promise<RawTransaction[]>
+```
+
+### Parameters
+
+```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)
+}
+```
+
+### Validations
+
+| 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()`          |
+
+### Return Type
+
+```ts
+RawTransaction[] // empty array if no open orders found
+```
+
+### Example
+
+```ts
+const txs = await rain.buildCancelAllOpenOrdersTx({
+  marketId: "698c8f116e985bbfacc7fc01",
+  marketContractAddress: "0xMarketContractAddress...",
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+  accessToken: "eyJhbGciOi...",
+});
+```
+
+---
+
+## buildCreateMarketTx
+
+Builds a **raw EVM transaction** for creating a market in Rain Protocol.
+
+This function **does not send the transaction** — it only prepares calldata.
+
+### Method Signature
+
+```ts
+buildCreateMarketTx(params: CreateMarketTxParams): Promise<RawTransaction[]>
+```
+
+### Parameters
+
+```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)
+}
+```
+
+### 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`                            |
+
+### Minimum Liquidity Rule
+
+#### inputAmountWei >= 10 tokens
+
+### Return Type
+
+```ts
+RawTransaction[] // [approve, createMarket] or [createMarket] depending on allowance
+```
+
+### Note
+
+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)**.
+
+### Example
+
+```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",
+});
+```
+
+---
+
+## buildClaimTx
+
+Builds a **raw EVM transaction** to claim funds from a resolved Rain market.
+
+This function **does not send the transaction** — it only prepares calldata.
+
+### Method Signature
+
+```ts
+buildClaimTx(params: ClaimTxParams): Promise<RawTransaction>
+```
+
+### Parameters
+
+```ts
+interface ClaimTxParams {
+  marketId: string;
+  walletAddress: `0x${string}`;
+}
+```
+
+### Validations
+
+| Parameter       | Type          | Required | Description                        |
+| --------------- | ------------- | -------- | ---------------------------------- |
+| `marketId`      | `string`      | ✅        | Unique identifier of the market    |
+| `walletAddress` | `0x${string}` | ✅        | Address of the user claiming funds |
+
+### Return Type
+
+```ts
+interface RawTransaction {
+  to: `0x${string}`;
+  data: `0x${string}`;
+}
+```
+
+### Example
+
+```ts
+const tx = await rain.buildClaimTx({
+  marketId: "698c8f116e985bbfacc7fc01",
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+});
+```
+
+---
+
+## 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.
+
+This function **does not send the transactions** — it only prepares calldata.
+
+### Method Signature
+
+```ts
+buildCloseMarketTx(params: CloseMarketTxParams): Promise<RawTransaction[]>
+```
+
+### Parameters
+
+```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
+}
+```
+
+### 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`                                          |
+
+### Return Type
+
+```ts
+RawTransaction[] // [approve?, closePool] for V3 or [closePool, chooseWinner] for V2
+```
+
+### Example
+
+```ts
+// V2 market
+const txs = await rain.buildCloseMarketTx({
+  marketId: "698c8f116e985bbfacc7fc01",
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+  proposedOutcome: 0,
+});
+
+// V3 manual resolver with RAIN token
+const txs = await rain.buildCloseMarketTx({
+  marketId: "698c8f116e985bbfacc7fc01",
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+  proposedOutcome: 1,
+  rainTokenAddress: "0xRainTokenAddress...",
+  usdtSymbol: "USDTm",
+});
+```
+
+---
+
+## buildCreateDisputeTx
+
+Builds **raw EVM transactions** to open a dispute on a Rain market.
+
+Checks the user's token allowance against the dispute fee and prepends an approval transaction if needed.
+
+This function **does not send the transactions** — it only prepares calldata.
+
+### Method Signature
+
+```ts
+buildCreateDisputeTx(params: CreateDisputeTxParams): Promise<RawTransaction[]>
+```
+
+### Parameters
+
+```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
+}
+```
+
+### Validations
+
+| 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            |
+
+### Return Type
+
+```ts
+RawTransaction[] // [approve?, openDispute]
+```
+
+### Example
+
+```ts
+const txs = await rain.buildCreateDisputeTx({
+  marketId: "698c8f116e985bbfacc7fc01",
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+  rainTokenAddress: "0xRainTokenAddress...",
+  usdtSymbol: "USDTm",
+});
+```
+
+---
+
+## buildCreateAppealTx
+
+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
+
+```ts
+buildCreateAppealTx(params: CreateAppealTxParams): Promise<RawTransaction[]>
+```
+
+### Parameters
+
+```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
+}
+```
+
+### Validations
+
+| 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            |
+
+### Return Type
+
+```ts
+RawTransaction[] // [approve?, openDispute]
+```
+
+### Example
+
+```ts
+const txs = await rain.buildCreateAppealTx({
+  marketId: "698c8f116e985bbfacc7fc01",
+  walletAddress: "0x996ea23940f4a01610181D04bdB6F862719b63f0",
+  rainTokenAddress: "0xRainTokenAddress...",
+  usdtSymbol: "USDTm",
+});
 ```
 
 ---
@@ -308,6 +846,8 @@ Raw Transaction
 RainAA (HOW to execute)
 ```
 
+---
+
 ## Versioning Policy
 
 Rain SDK follows **Semantic Versioning**:
@@ -321,12 +861,17 @@ Rain SDK follows **Semantic Versioning**:
 ## Recommended Usage Pattern
 
 ```ts
-// 1. Read data / build tx
-const rain = new Rain();
-const rawTx = rain.buildBuyOptionRawTx(...);
+// 1. Init SDK
+const rain = new Rain({ environment: "production" });
+
+// 2. Login
+const { accessToken } = await rain.login({ signature, walletAddress, smartWalletAddress });
 
-// 2. Execute via your provider
-await yourprovider.sendTransaction(rawTx);
+// 3. Read data / build tx
+const rawTx = await rain.buildBuyOptionRawTx({ ... });
+
+// 4. Execute via your provider
+await yourProvider.sendTransaction(rawTx);
 ```
 
 ---