rain-sdk-v2 2.1.2 → 2.1.4

package/README.md

@@ -1237,6 +1237,64 @@ const priceData = await rain.getTokenPrice('0x...'); // token contract address
 // priceData.data = { price: 0.05 } — USD price per token
 ```
 
+### Leaderboard
+
+Public endpoints — no access token required. Boards are served from a materialized document rebuilt by a cron (~20 min), so changes appear after the next tick rather than on the next request.
+
+```typescript
+// Get a ranked leaderboard — one board per (board, window, category)
+const board = await rain.getLeaderboard({
+  board: 'profit',        // 'profit' (net realized PnL) or 'correct_calls' (sum of 1 − entryPrice over winning positions)
+  window: 'all_time',     // 'all_time' (default) or 'monthly' (current UTC calendar month)
+  category: 'Crypto',     // optional, case-insensitive; omit for the global board
+  limit: 10,              // up to the stored cap of 100 (default 10)
+});
+// board.data = { board, window, category, categoryLabel, period, limit, totalRanked, priceBasis, entries, lastUpdatedAt }
+// Each entry carries all four table columns — profit, correctCalls, winRate, trades —
+// whichever board is sorting, so switching the sorted column needs no second request.
+
+// Search traders on a board — the leaderboard's trader search box
+const found = await rain.searchLeaderboard({
+  q: '0x742d',            // wallet address, address fragment (with/without 0x, prefix/middle/tail), or user id
+  board: 'profit',        // required — searches the stored board for this (board, window, category)
+  window: 'all_time',     // optional, default 'all_time'
+  category: 'Crypto',     // optional; omit for the global board
+  limit: 10,              // up to 50 (default 10)
+});
+// found.data = { board, window, category, period, query, matched, searchedTop, totalRanked, lastUpdatedAt, results }
+// `results` are the same entry objects getLeaderboard returns, in rank order.
+// Scoped to the stored board — a trader outside the top N is simply not found.
+// Empty `results` means "not on this board"; `searchedTop` + `totalRanked` let you
+// say "not in the top 100" precisely. Queries under 2 characters return empty, not a 400.
+
+// Get a trader's most recent trades — the rows inside an expanded leaderboard row
+const recent = await rain.getTraderRecentTrades({
+  userId: '...',          // from a leaderboard entry's `userId`
+  limit: 5,               // rendered rows (a multi-side trade flattens into more lines), up to 25 (default 5)
+});
+// recent.data = { userId, limit, trades }
+// Each trade: { action ('Buy'|'Sell'), origin, transactionHash, tradedAt, poolId, question,
+//               poolImage, subPoolId, subQuestion, side (1=YES, 2=NO), optionName, shares,
+//               amountUSD, pricePerShare, priceCents, status ('open'|'pending'|'settled'),
+//               pnlScope, pnlUSD }
+// Directional trades only (origin ∈ {enter, orderFill}), newest first — and unlike the
+// track-record endpoint, OPEN positions are included (status 'open').
+// `pnlUSD` is POSITION-level, not per-fill: several trades in the same market report the
+// same number. Null until settled; `amountUSD`/`pnlUSD` are dollars × 1e6.
+
+// Get categories that currently have a ranked board (feeds the category filter)
+const categories = await rain.getLeaderboardCategories();
+// categories.data = [{ category: 'CRYPTO', label: 'Crypto' }, ...]
+// Pass `category` back as the `category` param of getLeaderboard.
+```
+
+**Notes:**
+- **Units:** every `*USD` number (including `profit` and `score` on the profit board) is **dollars × 1e6** — divide by 1,000,000 to display. E.g. `profit: 887505347` is **$887.51**.
+- **Monthly window** buckets on when PnL *settled*, not when the position was opened; `window: 'monthly'` always means the current UTC month (`period` reports it as `YYYY-MM`).
+- **Only positive scores are ranked.** An unknown `category` returns an empty board, not a 400.
+- **Top-N only** — there is no rank-of-user lookup. Empty `entries` with `lastUpdatedAt: null` means the cron hasn't built the board yet; empty with a timestamp means nobody qualifies.
+- The client can highlight the viewer's own row by matching `userId` in `entries`.
+
 ---
 
 ## WebSocket Events (Socket.IO)

package/dist/Rain.d.ts

@@ -5,7 +5,7 @@ import { RainCoreConfig, RainEnvironment } from './types.js';
 import { LoginParams, LoginResult } from './auth/types.js';
 import { SellProceedsResult } from './markets/getSellProceeds.js';
 import { EntrySharesResult } from './markets/getEntryShares.js';
-import type { UserProfileUpdateParams, UserHistoryParams, CreateCommentParams, CommentsListingParams, UpdateCommentParams, CommentCountParams, PublicPoolsParams, PrivatePoolsParams, PoolListingByCreatorParams, VerifyAccessCodeParams, PoolTotalParticipantsParams, SearchPoolParams, RelatedPoolsParams, UpdateStreamingParams, UpdatePoolResolutionTimeParams, FindPoolFallbackParams, SignOraclesExtendTimeParams, TrendingTagsParams, UserTotalInvestmentParams, OptionsTotalVolumeParams, PoolActivityParams, TopHoldersParams, UserInvestedPoolsParams, InvestmentVolumeGraphParams, UserPnlGraphParams, TopWinnersLosersParams, PnlByPoolIdParams, UserPositionsParams, OpenPositionsParams, UserSharePositionsParams, SearchInvestedPoolsParams, PriceDataParams, AddReviewParams, GetUserOrdersParams, OrderBookParams, GetUserOrderByPoolIdParams, OrdersListingByPoolParams, AddUserPointsParams, UserOnboardingParams, PointsGraphParams, GetNotificationsParams, MarkNotificationAsReadParams, CreateDisputeMessageParams, GetPoolDisputeConvoParams, FollowToggleParams, FollowCheckParams, FollowListParams, FollowStatsParams, RainBurnPerPoolParams, ToggleBookmarkParams, GetBookmarksParams, CheckBookmarkParams } from './api/types.js';
+import type { UserProfileUpdateParams, UserHistoryParams, CreateCommentParams, CommentsListingParams, UpdateCommentParams, CommentCountParams, PublicPoolsParams, PrivatePoolsParams, PoolListingByCreatorParams, VerifyAccessCodeParams, PoolTotalParticipantsParams, SearchPoolParams, RelatedPoolsParams, UpdateStreamingParams, UpdatePoolResolutionTimeParams, FindPoolFallbackParams, SignOraclesExtendTimeParams, TrendingTagsParams, UserTotalInvestmentParams, OptionsTotalVolumeParams, PoolActivityParams, TopHoldersParams, UserInvestedPoolsParams, InvestmentVolumeGraphParams, UserPnlGraphParams, TopWinnersLosersParams, PnlByPoolIdParams, UserPositionsParams, OpenPositionsParams, UserSharePositionsParams, SearchInvestedPoolsParams, PriceDataParams, AddReviewParams, GetUserOrdersParams, OrderBookParams, GetUserOrderByPoolIdParams, OrdersListingByPoolParams, AddUserPointsParams, UserOnboardingParams, PointsGraphParams, GetNotificationsParams, MarkNotificationAsReadParams, CreateDisputeMessageParams, GetPoolDisputeConvoParams, FollowToggleParams, FollowCheckParams, FollowListParams, FollowStatsParams, RainBurnPerPoolParams, ToggleBookmarkParams, GetBookmarksParams, CheckBookmarkParams, LeaderboardParams, LeaderboardSearchParams, TraderRecentTradesParams } from './api/types.js';
 export declare class Rain {
     readonly environment: RainEnvironment;
     private readonly marketFactory;
@@ -235,7 +235,7 @@ export declare class Rain {
     checkTokenExpiration(accessToken: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
     updatePoolResolutionTime(params: UpdatePoolResolutionTimeParams, accessToken: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
     findPoolFallback(params: FindPoolFallbackParams, accessToken: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
-    getTrendingTags(params: TrendingTagsParams, accessToken?: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
+    getTrendingTags(params: TrendingTagsParams): Promise<import("./api/types.js").ApiResponse<unknown>>;
     getFeaturedPools(accessToken?: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
     getUserTotalInvestment(params: UserTotalInvestmentParams, accessToken: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
     getOptionsTotalVolume(params: OptionsTotalVolumeParams, accessToken?: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
@@ -292,4 +292,8 @@ export declare class Rain {
     toggleBookmark(params: ToggleBookmarkParams, accessToken: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
     getBookmarks(params: GetBookmarksParams, accessToken: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
     checkBookmark(params: CheckBookmarkParams, accessToken: string): Promise<import("./api/types.js").ApiResponse<unknown>>;
+    getLeaderboard(params: LeaderboardParams): Promise<import("./api/types.js").ApiResponse<import("./api/types.js").LeaderboardData>>;
+    searchLeaderboard(params: LeaderboardSearchParams): Promise<import("./api/types.js").ApiResponse<import("./api/types.js").LeaderboardSearchData>>;
+    getTraderRecentTrades(params: TraderRecentTradesParams): Promise<import("./api/types.js").ApiResponse<import("./api/types.js").TraderRecentTradesData>>;
+    getLeaderboardCategories(): Promise<import("./api/types.js").ApiResponse<import("./api/types.js").LeaderboardCategory[]>>;
 }

package/dist/Rain.js

@@ -41,6 +41,7 @@ import * as disputeApi from './api/dispute.js';
 import * as followApi from './api/follow.js';
 import * as whitelistedTokensApi from './api/whitelistedTokens.js';
 import * as bookmarksApi from './api/bookmarks.js';
+import * as leaderboardApi from './api/leaderboard.js';
 const erc20AllowanceAbi = parseAbi(['function allowance(address owner, address spender) view returns (uint256)']);
 const factoryViewAbi = parseAbi([
     'function oracleFixedFee() view returns (uint256)',
@@ -333,8 +334,8 @@ export class Rain {
     async findPoolFallback(params, accessToken) {
         return poolsApi.findPoolFallback(params, this.cfg(accessToken));
     }
-    async getTrendingTags(params, accessToken) {
-        return poolsApi.getTrendingTags(params, this.cfg(accessToken));
+    async getTrendingTags(params) {
+        return poolsApi.getTrendingTags(params, this.cfg());
     }
     async getFeaturedPools(accessToken) {
         return poolsApi.getFeaturedPools(this.cfg(accessToken));
@@ -503,4 +504,17 @@ export class Rain {
     async checkBookmark(params, accessToken) {
         return bookmarksApi.checkBookmark(params, this.cfg(accessToken));
     }
+    // ─── Leaderboard ────────────────────────────────────────────────────────────
+    async getLeaderboard(params) {
+        return leaderboardApi.getLeaderboard(params, this.cfg());
+    }
+    async searchLeaderboard(params) {
+        return leaderboardApi.searchLeaderboard(params, this.cfg());
+    }
+    async getTraderRecentTrades(params) {
+        return leaderboardApi.getTraderRecentTrades(params, this.cfg());
+    }
+    async getLeaderboardCategories() {
+        return leaderboardApi.getLeaderboardCategories(this.cfg());
+    }
 }

package/dist/api/index.d.ts

@@ -14,3 +14,4 @@ export * from './dispute.js';
 export * from './follow.js';
 export * from './whitelistedTokens.js';
 export * from './bookmarks.js';
+export * from './leaderboard.js';

package/dist/api/index.js

@@ -14,3 +14,4 @@ export * from './dispute.js';
 export * from './follow.js';
 export * from './whitelistedTokens.js';
 export * from './bookmarks.js';
+export * from './leaderboard.js';

package/dist/api/leaderboard.d.ts

@@ -0,0 +1,5 @@
+import { ApiConfig, ApiResponse, LeaderboardParams, LeaderboardData, LeaderboardCategory, LeaderboardSearchParams, LeaderboardSearchData, TraderRecentTradesParams, TraderRecentTradesData } from './types.js';
+export declare function getLeaderboard(params: LeaderboardParams, config: ApiConfig): Promise<ApiResponse<LeaderboardData>>;
+export declare function searchLeaderboard(params: LeaderboardSearchParams, config: ApiConfig): Promise<ApiResponse<LeaderboardSearchData>>;
+export declare function getTraderRecentTrades(params: TraderRecentTradesParams, config: ApiConfig): Promise<ApiResponse<TraderRecentTradesData>>;
+export declare function getLeaderboardCategories(config: ApiConfig): Promise<ApiResponse<LeaderboardCategory[]>>;

package/dist/api/leaderboard.js

@@ -0,0 +1,32 @@
+import { buildHeaders, buildQuery, handleResponse } from './helpers.js';
+export async function getLeaderboard(params, config) {
+    const qs = buildQuery({ board: params.board, window: params.window, category: params.category, limit: params.limit });
+    const res = await fetch(`${config.apiUrl}/leaderboard${qs}`, {
+        method: 'GET',
+        headers: buildHeaders(config),
+    });
+    return handleResponse(res);
+}
+export async function searchLeaderboard(params, config) {
+    const qs = buildQuery({ q: params.q, board: params.board, window: params.window, category: params.category, limit: params.limit });
+    const res = await fetch(`${config.apiUrl}/leaderboard/search${qs}`, {
+        method: 'GET',
+        headers: buildHeaders(config),
+    });
+    return handleResponse(res);
+}
+export async function getTraderRecentTrades(params, config) {
+    const qs = buildQuery({ limit: params.limit });
+    const res = await fetch(`${config.apiUrl}/leaderboard/traders/${encodeURIComponent(params.userId)}/recent-trades${qs}`, {
+        method: 'GET',
+        headers: buildHeaders(config),
+    });
+    return handleResponse(res);
+}
+export async function getLeaderboardCategories(config) {
+    const res = await fetch(`${config.apiUrl}/leaderboard/categories`, {
+        method: 'GET',
+        headers: buildHeaders(config),
+    });
+    return handleResponse(res);
+}

package/dist/api/types.d.ts

@@ -322,3 +322,141 @@ export interface GetBookmarksParams {
 export interface CheckBookmarkParams {
     poolId: string;
 }
+export type LeaderboardBoard = 'profit' | 'correct_calls';
+export type LeaderboardWindow = 'all_time' | 'monthly';
+export interface LeaderboardParams {
+    /** Ranking to serve: net realized PnL, or the weighted correct-calls score. */
+    board: LeaderboardBoard;
+    /** `all_time` (default) or the current UTC calendar month. */
+    window?: LeaderboardWindow;
+    /** Market category (case-insensitive). Omit for the global board. Unknown categories return an empty board. */
+    category?: string;
+    /** Entries to return, up to the stored cap of 100. Default 10. */
+    limit?: number;
+}
+export interface LeaderboardEntry {
+    rank: number;
+    userId: string;
+    walletAddress: string | null;
+    eoaWalletAddress: string | null;
+    /** The ranking key. On `profit`, dollars × 1e6 (divide by 1,000,000 to display); on `correct_calls`, an unscaled weight. */
+    score: number;
+    positions: number;
+    /** Net realized PnL in dollars × 1e6. Present on both boards. */
+    profit: number;
+    /** Sum of `1 − entryPrice` over winning positions — a weight, not a count. Present on both boards. */
+    correctCalls: number;
+    /** Resolved directional positions — the denominator of `winRate`. */
+    trades: number;
+    wins: number;
+    /** `wins / trades`, a fraction in [0,1]. */
+    winRate: number;
+    badge: 'none' | 'blue' | 'gold';
+    /** Crowns held on this board and category — the row's crown indicator. */
+    categoryCrowns: number;
+    /** Newest crowned month in this bucket, `YYYY-MM` (UTC), or null. */
+    lastCrownPeriod: string | null;
+    /** Crowns held across all boards and categories. */
+    crownCount: number;
+    marketScore: number;
+    costScore: number;
+}
+export interface LeaderboardData {
+    board: LeaderboardBoard;
+    window: LeaderboardWindow;
+    /** Upper-cased matched key, or null for the global board. */
+    category: string | null;
+    /** Display spelling of the matched category, or null. */
+    categoryLabel: string | null;
+    /** `YYYY-MM` (UTC) on the monthly window; null on all-time. */
+    period: string | null;
+    limit: number;
+    /** Users ranked in total (before the stored cap). */
+    totalRanked: number;
+    /** Entry-price basis the correct-calls board was ranked on: `market` or `cost`. */
+    priceBasis: 'market' | 'cost';
+    entries: LeaderboardEntry[];
+    /** When the cron last rebuilt this board; null means never. */
+    lastUpdatedAt: string | null;
+}
+export interface LeaderboardCategory {
+    /** Upper-cased key — pass this back as `category`. */
+    category: string;
+    /** First-seen spelling, for display. */
+    label: string;
+}
+export interface LeaderboardSearchParams {
+    /** Wallet address, address fragment (with or without 0x, prefix/middle/tail), or user id. Case-insensitive substring match. */
+    q: string;
+    /** Board to search: `profit` or `correct_calls`. */
+    board: LeaderboardBoard;
+    /** `all_time` (default) or the current UTC calendar month. */
+    window?: LeaderboardWindow;
+    /** Market category (case-insensitive). Omit for the global board. */
+    category?: string;
+    /** Results to return, up to 50. Default 10. */
+    limit?: number;
+}
+export interface TraderRecentTradesParams {
+    /** The trader's user id, as returned in leaderboard entries. */
+    userId: string;
+    /** Rendered rows to return (a trade carrying more than one side flattens into more than one line), up to 25. Default 5. */
+    limit?: number;
+}
+export interface TraderRecentTrade {
+    /** Rendered form of `transactionType`: `Buy` or `Sell`. */
+    action: 'Buy' | 'Sell';
+    transactionType: string;
+    origin: 'enter' | 'orderFill';
+    transactionHash: string;
+    tradedAt: string;
+    poolId: string;
+    question: string | null;
+    poolImage: string | null;
+    subPoolId: string | null;
+    /** The sub-market — e.g. "Match winner". */
+    subQuestion: string | null;
+    /** 1 = YES, 2 = NO */
+    side: number;
+    optionName: string;
+    shares: number;
+    /** Collateral paid, in dollars × 1e6 (divide by 1,000,000 to display). */
+    amountUSD: number;
+    /** Collateral paid per share, in (0,1). Null when the recorded ratio is not a price (e.g. a 1:1 AMM entry). */
+    pricePerShare: number | null;
+    /** `pricePerShare` in cents, for the "9c" label. */
+    priceCents: number | null;
+    /** `open` = market not resolved; `pending` = won but unclaimed (no PnL yet, never booked as a loss); `settled` = realized. */
+    status: 'open' | 'pending' | 'settled';
+    /** Always `position` — PnL is per (pool, subPool), not per fill. */
+    pnlScope: string;
+    /** Realized PnL of the POSITION this trade belongs to, in dollars × 1e6. Null until settled. */
+    pnlUSD: number | null;
+    /** Resolved-but-unclaimed winnings of the position, in dollars × 1e6. */
+    pendingUSD?: number;
+    /** Whether the position won, once resolved. */
+    won?: boolean;
+}
+export interface TraderRecentTradesData {
+    userId: string;
+    limit: number;
+    /** Most recent directional trades, newest first. */
+    trades: TraderRecentTrade[];
+}
+export interface LeaderboardSearchData {
+    board: LeaderboardBoard;
+    window: LeaderboardWindow;
+    category: string | null;
+    /** `YYYY-MM` (UTC) on the monthly window; null on all-time. */
+    period: string | null;
+    query: string;
+    /** Board entries the term matched, before `limit`. */
+    matched: number;
+    /** Board rows searched — the stored depth. With `matched: 0`, lets a client say "not in the top N" rather than "no such trader". */
+    searchedTop: number;
+    /** Users ranked on this board in total. */
+    totalRanked: number;
+    lastUpdatedAt: string | null;
+    /** Matching board entries — the same objects `getLeaderboard` returns, in rank order. */
+    results: LeaderboardEntry[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rain-sdk-v2",
-    "version": "2.1.2",
+    "version": "2.1.4",
     "type": "module",
     "description": "Rain SDK V2 — TypeScript SDK for Rain prediction markets on Arbitrum. Market creation, trading, liquidity, order book, split/merge, dispute, and smart account support.",
     "main": "dist/index.js",