Update the leaderboard Nuanze endpoints

Author: przemekink

apps/e2e/src/nuanze-client/leaderboardQueries.test.ts

@@ -30,13 +30,14 @@ Nuanze runs a single public deployment that serves mainnet data, so every entry
 ## API Surface
 
 Each method maps one-to-one onto a public operation. Most are GET; `getFollowedLeaderboard` is a
-non-mutating POST whose body carries the followed set:
+non-mutating POST whose body names the username whose followed accounts should be ranked:
 
 - `getNews`
 - `getMarkets`
 - `getMarketByTicker`
 - `getFundingRates`
 - `getLeaderboard`
+- `getSubaccountLeaderboard`
 - `getPlatformSummary`
 - `getFollowedLeaderboard`
 - `getWalletSummary`

packages/nuanze-client/README.md

@@ -15,6 +15,7 @@ import {
   mapNuanzeNewsResponse,
   mapNuanzeOpenPositionsResponse,
   mapNuanzePlatformSummaryResponse,
+  mapNuanzeSubaccountLeaderboardResponse,
   mapNuanzeWalletPnlResponse,
   mapNuanzeWalletPnlSeriesResponse,
   mapNuanzeWalletPositionsResponse,
@@ -52,6 +53,8 @@ import {
   GetNuanzeOpenPositionsResponse,
   GetNuanzePlatformSummaryParams,
   GetNuanzePlatformSummaryResponse,
+  GetNuanzeSubaccountLeaderboardParams,
+  GetNuanzeSubaccountLeaderboardResponse,
   GetNuanzeWalletPnlParams,
   GetNuanzeWalletPnlResponse,
   GetNuanzeWalletPnlSeriesParams,
@@ -80,6 +83,7 @@ import {
   NuanzeServerNewsResponse,
   NuanzeServerOpenPositionsResponse,
   NuanzeServerPlatformSummaryResponse,
+  NuanzeServerSubaccountLeaderboardResponse,
   NuanzeServerWalletPnlResponse,
   NuanzeServerWalletPnlSeriesResponse,
   NuanzeServerWalletPositionsResponse,
@@ -106,8 +110,8 @@ export interface NuanzeClientOpts {
  * linked signer. It also sends no `x-nado-client-type` header: Nuanze is a public API that does not
  * attribute traffic per client, and its `Access-Control-Allow-Headers` does not list the header, so
  * sending it would fail CORS preflight in the browser. Most operations are GET;
- * {@link NuanzeClient.getFollowedLeaderboard} is a non-mutating POST whose body carries a followed
- * set larger than a query string can reliably hold.
+ * {@link NuanzeClient.getFollowedLeaderboard} is a non-mutating POST whose body identifies the
+ * username whose follow graph should be ranked.
  */
 export class NuanzeClient {
   readonly opts: NuanzeClientOpts;
@@ -213,6 +217,25 @@ export class NuanzeClient {
     );
   }
 
+  /**
+   * Gets the global public leaderboard of username-claimed subaccounts. Results are sorted by
+   * equity-basis account PnL descending with nulls last. `globalRank` is independent of the active
+   * privacy and trading filters. Pagination uses a filter-bound opaque cursor.
+   *
+   * @throws {NuanzeServerFailureError} With `BAD_REQUEST`, `INVALID_CURSOR`, or
+   * `CURSOR_FILTER_MISMATCH` when filters or the cursor are invalid.
+   */
+  async getSubaccountLeaderboard(
+    params: GetNuanzeSubaccountLeaderboardParams = {},
+  ): Promise<GetNuanzeSubaccountLeaderboardResponse> {
+    return mapNuanzeSubaccountLeaderboardResponse(
+      await this.getJson<NuanzeServerSubaccountLeaderboardResponse>(
+        '/leaderboard/subaccounts',
+        params,
+      ),
+    );
+  }
+
   /**
    * Gets platform activity summary from five-minute aggregates.
    *
@@ -230,14 +253,12 @@ export class NuanzeClient {
   }
 
   /**
-   * Gets leaderboard stats for a set of followed subaccounts. POST rather than GET so the body can
-   * carry up to 300 `subaccountHex` values. The response preserves request order. Subaccounts with
-   * no data in the window are backfilled with `pnl: null`, `globalRank: null`, zero counts, and an
-   * empty `productIds`. The response is not cached.
+   * Gets leaderboard stats for the subaccounts a username actively follows, capped at 300 and
+   * sorted by PnL descending with nulls last. Subaccounts with no PnL in the window are included by
+   * default with null PnL/rank, zero counts, and no products. The response is not cached.
    *
-   * @throws {NuanzeServerFailureError} With `INVALID_SUBACCOUNT` if a hex is not 32-byte
-   * 0x-prefixed, and `BAD_REQUEST` if the set is empty, exceeds 300, or `timeframe` is not a
-   * documented value.
+   * @throws {NuanzeServerFailureError} With `BAD_REQUEST` when params are invalid, or
+   * `USERNAME_NOT_FOUND` when the supplied username has no claimed identity.
    */
   async getFollowedLeaderboard(
     params: GetNuanzeFollowedLeaderboardParams,

packages/nuanze-client/src/NuanzeClient.ts

@@ -23,6 +23,7 @@ import {
   NuanzePositioningTotals,
   NuanzeSeriesPoint,
   NuanzeStockFundamentals,
+  NuanzeSubaccountLeaderboardItem,
   NuanzeWalletPosition,
   NuanzeWalletTrade,
 } from './types/clientModelTypes';
@@ -42,6 +43,7 @@ import {
   GetNuanzeNewsResponse,
   GetNuanzeOpenPositionsResponse,
   GetNuanzePlatformSummaryResponse,
+  GetNuanzeSubaccountLeaderboardResponse,
   GetNuanzeWalletPnlResponse,
   GetNuanzeWalletPnlSeriesResponse,
   GetNuanzeWalletPositionsResponse,
@@ -75,6 +77,7 @@ import {
   NuanzeServerSeriesPoint,
   NuanzeServerSidePositioningCell,
   NuanzeServerStockFundamentals,
+  NuanzeServerSubaccountLeaderboardItem,
   NuanzeServerWalletPosition,
   NuanzeServerWalletTrade,
 } from './types/serverModelTypes';
@@ -92,6 +95,7 @@ import {
   NuanzeServerNewsResponse,
   NuanzeServerOpenPositionsResponse,
   NuanzeServerPlatformSummaryResponse,
+  NuanzeServerSubaccountLeaderboardResponse,
   NuanzeServerWalletPnlResponse,
   NuanzeServerWalletPnlSeriesResponse,
   NuanzeServerWalletPositionsResponse,
@@ -335,6 +339,8 @@ export function mapNuanzeLeaderboardItem(
     wins: server.wins,
     losses: server.losses,
     winRate: mapNuanzeDecimal(server.winRate),
+    productIds: server.productIds,
+    productCount: server.productCount,
   };
 }
 
@@ -362,6 +368,29 @@ export function mapNuanzeFollowedLeaderboardItem(
 ): NuanzeFollowedLeaderboardItem {
   return {
     subaccountHex: server.subaccountHex,
+    username: server.username,
+    displayName: server.displayName,
+    pnl: mapNuanzeDecimal(server.pnl),
+    wins: server.wins,
+    losses: server.losses,
+    winRate: mapNuanzeDecimal(server.winRate),
+    trades: server.trades,
+    productIds: server.productIds,
+    productCount: server.productCount,
+    globalRank: server.globalRank,
+  };
+}
+
+/**
+ * Maps a server-side public subaccount leaderboard row.
+ */
+export function mapNuanzeSubaccountLeaderboardItem(
+  server: NuanzeServerSubaccountLeaderboardItem,
+): NuanzeSubaccountLeaderboardItem {
+  return {
+    subaccountHex: server.subaccountHex,
+    username: server.username,
+    displayName: server.displayName,
     pnl: mapNuanzeDecimal(server.pnl),
     wins: server.wins,
     losses: server.losses,
@@ -373,6 +402,21 @@ export function mapNuanzeFollowedLeaderboardItem(
   };
 }
 
+/**
+ * Maps a server-side `GET /leaderboard/subaccounts` response.
+ */
+export function mapNuanzeSubaccountLeaderboardResponse(
+  server: NuanzeServerSubaccountLeaderboardResponse,
+): GetNuanzeSubaccountLeaderboardResponse {
+  return {
+    timeframe: server.timeframe,
+    totalCount: server.totalCount,
+    items: server.items.map(mapNuanzeSubaccountLeaderboardItem),
+    nextCursor: server.nextCursor,
+    asOf: server.asOf,
+  };
+}
+
 /**
  * Maps a server-side `POST /wallets/leaderboard` response.
  */

packages/nuanze-client/src/dataMappers.ts

@@ -660,15 +660,18 @@ export interface NuanzeMarketDetail extends NuanzeMarket {
 }
 
 /**
- * Per-subaccount row from `POST /wallets/leaderboard`. Unknown or window-younger
- * subaccounts are backfilled with `pnl: null`, `globalRank: null`, zero counts, and
- * an empty `productIds`.
+ * Per-subaccount row from `POST /wallets/leaderboard`. Untraded followed subaccounts are included
+ * by default with null PnL/rank/name fields where unavailable, zero counts, and no products.
  */
 export interface NuanzeFollowedLeaderboardItem {
   /**
    * Lowercase bytes32 subaccount hex (owner + name), the SDK `subaccountToHex` form.
    */
   subaccountHex: string;
+  /** Canonical username, or null when the followed subaccount has not claimed one. */
+  username: string | null;
+  /** User-facing display name, or null when the followed subaccount has not claimed one. */
+  displayName: string | null;
   /**
    * Equity-basis account PnL for the requested timeframe, or null when the subaccount
    * has no data in the window.
@@ -693,6 +696,42 @@ export interface NuanzeFollowedLeaderboardItem {
   globalRank: number | null;
 }
 
+/**
+ * Username-claimed subaccount row from `GET /leaderboard/subaccounts`.
+ */
+export interface NuanzeSubaccountLeaderboardItem {
+  /**
+   * Lowercase bytes32 subaccount hex (owner + name), the SDK `subaccountToHex` form.
+   */
+  subaccountHex: string;
+  /** Canonical username claimed by this subaccount. */
+  username: string;
+  /** User-facing display name, or null when unavailable. */
+  displayName: string | null;
+  /**
+   * Equity-basis account PnL for the requested timeframe, or null for an untraded subaccount
+   * returned when `includeUntraded` is enabled.
+   */
+  pnl: BigNumber | null;
+  /** Close-derived win count. */
+  wins: number;
+  /** Close-derived loss count. */
+  losses: number;
+  /** Win rate, or null when there are no closed trades. */
+  winRate: BigNumber | null;
+  /** Perp fill count in the window. */
+  trades: number;
+  /** Traded product IDs, sorted by fill count descending. */
+  productIds: number[];
+  /** Number of distinct traded products. Equals `productIds.length`. */
+  productCount: number;
+  /**
+   * Rank across all subaccounts for the timeframe, independent of page filters, or null when the
+   * subaccount has no PnL in the window.
+   */
+  globalRank: number | null;
+}
+
 /**
  * Leaderboard row. PnL is equity-basis account PnL, not realized PnL.
  */
@@ -719,6 +758,10 @@ export interface NuanzeLeaderboardItem {
   losses: number;
   /** Win rate, or null when there are no closed trades. */
   winRate: BigNumber | null;
+  /** Traded product IDs, sorted by fill count descending. */
+  productIds: number[];
+  /** Number of distinct traded products. Equals `productIds.length`. */
+  productCount: number;
 }
 
 /**

packages/nuanze-client/src/types/clientModelTypes.ts

@@ -36,6 +36,7 @@ import {
   NuanzeSeriesMetric,
   NuanzeSeriesPoint,
   NuanzeSourceInterval,
+  NuanzeSubaccountLeaderboardItem,
   NuanzeWalletPosition,
   NuanzeWalletTrade,
 } from './clientModelTypes';
@@ -169,18 +170,52 @@ export interface GetNuanzeLeaderboardResponse {
   asOf: string;
 }
 
+/**
+ * Params for `NuanzeClient.getSubaccountLeaderboard`.
+ */
+export interface GetNuanzeSubaccountLeaderboardParams {
+  /** Ranking window, default `30d`. */
+  timeframe?: NuanzeLeaderboardTimeframe;
+  /** Page size, 1-200, default 100. */
+  limit?: number;
+  /**
+   * Opaque cursor from the previous page. It is bound to the normalized filters and must be
+   * returned unchanged.
+   */
+  cursor?: string;
+  /** Include subaccounts with Private Mode enabled, default false. */
+  includePrivate?: boolean;
+  /** Include subaccounts with no PnL in the requested window, default false. */
+  includeUntraded?: boolean;
+}
+
+/**
+ * Response of `NuanzeClient.getSubaccountLeaderboard`.
+ */
+export interface GetNuanzeSubaccountLeaderboardResponse {
+  /** Echoed timeframe. */
+  timeframe: NuanzeLeaderboardTimeframe;
+  /** Total username-claimed subaccounts matching the active filters. */
+  totalCount: number;
+  /** Ranked rows for this page. */
+  items: NuanzeSubaccountLeaderboardItem[];
+  /** Opaque cursor for the next page, or null when this is the final page. */
+  nextCursor: string | null;
+  /** When the response was generated, as a UTC ISO 8601 string. */
+  asOf: string;
+}
+
 /**
  * Params for `NuanzeClient.getFollowedLeaderboard`. `timeframe` is required and applies to
  * every per-subaccount figure.
  */
 export interface GetNuanzeFollowedLeaderboardParams {
-  /**
-   * Followed subaccounts as bytes32 hex (owner + name). Mixed case is accepted and
-   * normalized to lowercase. 1-300 items; the response preserves this order.
-   */
-  subaccounts: string[];
+  /** Username whose active follow graph should be ranked. */
+  username: string;
   /** Ranking window for every per-subaccount figure. */
   timeframe: NuanzeLeaderboardTimeframe;
+  /** Include followed subaccounts with no PnL in the requested window, default true. */
+  includeUntraded?: boolean;
 }
 
 /**
@@ -189,9 +224,9 @@ export interface GetNuanzeFollowedLeaderboardParams {
 export interface GetNuanzeFollowedLeaderboardResponse {
   /** Echoed timeframe. */
   timeframe: NuanzeLeaderboardTimeframe;
-  /** One row per requested hex, in request order. */
+  /** Actively followed subaccounts, sorted by PnL descending with nulls last. */
   items: NuanzeFollowedLeaderboardItem[];
-  /** Number of rows returned. Equals `items.length` and the request length. */
+  /** Number of rows returned. Equals `items.length`. */
   count: number;
   /** When the response was generated, as a UTC ISO 8601 string. */
   asOf: string;

packages/nuanze-client/src/types/clientTypes.ts

@@ -13,6 +13,7 @@ export const NUANZE_ERROR_CODES = [
   'MARKET_SELECTOR_MISMATCH',
   'MARKET_NOT_FOUND',
   'WALLET_NOT_FOUND',
+  'USERNAME_NOT_FOUND',
   'UNSUPPORTED_INTERVAL',
   'UNSUPPORTED_BUCKET',
   'RANGE_TOO_LARGE',

packages/nuanze-client/src/types/nuanzeErrorCodes.ts

@@ -163,13 +163,34 @@ export interface NuanzeServerLeaderboardItem {
   wins: number;
   losses: number;
   winRate: string | null;
+  productIds: number[];
+  productCount: number;
 }
 
 /**
  * Followed-leaderboard row as returned on the wire.
  */
 export interface NuanzeServerFollowedLeaderboardItem {
   subaccountHex: string;
+  username: string | null;
+  displayName: string | null;
+  pnl: string | null;
+  wins: number;
+  losses: number;
+  winRate: string | null;
+  trades: number;
+  productIds: number[];
+  productCount: number;
+  globalRank: number | null;
+}
+
+/**
+ * Public subaccount leaderboard row as returned on the wire.
+ */
+export interface NuanzeServerSubaccountLeaderboardItem {
+  subaccountHex: string;
+  username: string;
+  displayName: string | null;
   pnl: string | null;
   wins: number;
   losses: number;