@uniswap/client-data-api 0.0.168 → 0.0.170

package/dist/data/v2/api_pb.d.ts

@@ -1565,9 +1565,25 @@ export declare class GetTokenTopTradersRequest extends Message<GetTokenTopTrader
  * so re-entering wallets are accounted correctly. Auction claims are seeded
  * before the trade walk as buys at the wallet's true auction cost, so
  * bidders never show zero buys. Tokens sold beyond tracked inventory
- * (transfers in) carry a zero basis — with the full history and explicit
- * claims in hand, an unexplained inflow is a transfer, not a hidden buy —
- * and flag transferred_in.
+ * (transfers in) entered the wallet outside the swap tape — with the full
+ * history and explicit claims in hand, an unexplained inflow is a transfer,
+ * not a hidden buy — so the wallet's basis is UNKNOWN (not $0) and the row
+ * flags transferred_in.
+ *
+ * UNKNOWN-BASIS ROWS: when the server cannot compute a wallet's basis — the
+ * wallet transferred tokens in (transferred_in), or its auction spend was
+ * not USD-convertible — basis_unknown is true and the four basis-derived
+ * money fields (cost_basis_usd, avg_cost_usd, realized_pnl_usd,
+ * unrealized_pnl_usd) are served as 0 and MUST be read as "unknown", never
+ * as a real $0.00. Such wallets rank strictly after every computable-PnL
+ * row — including loss-makers: an unknown 0 never outranks a real figure —
+ * so a transfer-in whale's raw proceeds can never crowd real traders out
+ * of the request limit. Observed figures (buys/sells/proceeds/tokens) are
+ * always set and always truthful. unrealized_pnl_unknown additionally
+ * covers the basis-known wallet whose unrealized leg alone is uncomputable
+ * (token has no spot price). (These are flags rather than proto3 `optional`
+ * on the money fields because changing an existing field's presence is a
+ * breaking gencode change for published clients.)
  *
  * @generated from message data.v2.TokenTopTrader
  */
@@ -1616,19 +1632,23 @@ export declare class TokenTopTrader extends Message<TokenTopTrader> {
     remainingTokens: number;
     /**
      * USD cost basis of the REMAINING position: grows with buys/claims,
-     * shrinks by average cost × amount on every sell.
+     * shrinks by average cost × amount on every sell. Meaningless (served 0)
+     * when basis_unknown — read that as "unknown", not a zero basis.
      *
      * @generated from field: double cost_basis_usd = 9;
      */
     costBasisUsd: number;
     /**
-     * cost_basis_usd ÷ remaining_tokens; 0 for wallets holding nothing (or
-     * with no tracked basis).
+     * cost_basis_usd ÷ remaining_tokens; 0 for wallets holding nothing.
+     * Meaningless (served 0) when basis_unknown.
      *
      * @generated from field: double avg_cost_usd = 10;
      */
     avgCostUsd: number;
     /**
+     * Meaningless (served 0) when basis_unknown — proceeds booked against an
+     * unknowable basis are not a PnL; such rows rank as realized 0.
+     *
      * @generated from field: double realized_pnl_usd = 11;
      */
     realizedPnlUsd: number;
@@ -1650,20 +1670,39 @@ export declare class TokenTopTrader extends Message<TokenTopTrader> {
     /**
      * Mark-to-market PnL of the remaining position at the token's latest
      * known price: remaining_tokens × (spot − avg_cost_usd). The documented
-     * ranking tiebreak, served so clients can render it.
+     * ranking tiebreak, served so clients can render it. Meaningless (served
+     * 0) when unrealized_pnl_unknown — basis unknown, or no known spot price.
      *
      * @generated from field: double unrealized_pnl_usd = 14;
      */
     unrealizedPnlUsd: number;
     /**
      * True when the wallet sold beyond its tracked inventory at least once —
-     * the excess entered the wallet outside the swap tape (a transfer in)
-     * and carries a zero basis. Distinguishes a genuine transfer from a
-     * data gap when cost_basis_usd is 0.
+     * the excess entered the wallet outside the swap tape (a transfer in),
+     * so its basis is unknown. Always implies basis_unknown.
      *
      * @generated from field: bool transferred_in = 15;
      */
     transferredIn: boolean;
+    /**
+     * True when the wallet's basis could not be computed — it transferred
+     * tokens in (transferred_in), or its auction spend was not
+     * USD-convertible. Clients should render the four basis-derived money
+     * fields as unknown ("–"), not $0.00; the row ranks after every
+     * computable-PnL row (see message doc). Implies unrealized_pnl_unknown.
+     *
+     * @generated from field: bool basis_unknown = 16;
+     */
+    basisUnknown: boolean;
+    /**
+     * True when unrealized_pnl_usd alone is not computable: basis_unknown, or
+     * the token has no known spot price (a missing spot must not read as a
+     * total loss). Served 0 then — render unknown ("–"), not $0.00. The other
+     * money fields stay real when basis_unknown is false.
+     *
+     * @generated from field: bool unrealized_pnl_unknown = 17;
+     */
+    unrealizedPnlUnknown: boolean;
     constructor(data?: PartialMessage<TokenTopTrader>);
     static readonly runtime: typeof proto3;
     static readonly typeName = "data.v2.TokenTopTrader";
@@ -1679,8 +1718,12 @@ export declare class TokenTopTrader extends Message<TokenTopTrader> {
 export declare class GetTokenTopTradersResponse extends Message<GetTokenTopTradersResponse> {
     /**
      * Ranked realized PnL desc, unrealized PnL desc as the tiebreak (orders
-     * never-sold claimers sensibly — all realized 0), capped at the request
-     * limit. Only wallets with at least one trade or claim appear.
+     * never-sold claimers sensibly — all realized 0), wallet address asc as
+     * the final key, capped at the request limit. Unknown-basis rows
+     * (transferred_in, or an inconvertible auction spend) partition strictly
+     * after every computable-PnL row, including losses — so they cannot
+     * consume top slots on raw proceeds or displace losing traders. Only
+     * wallets with at least one trade or claim appear.
      *
      * @generated from field: repeated data.v2.TokenTopTrader traders = 1;
      */

package/dist/data/v2/api_pb.js

@@ -1975,9 +1975,25 @@ GetTokenTopTradersRequest.fields = proto3.util.newFieldList(() => [
  * so re-entering wallets are accounted correctly. Auction claims are seeded
  * before the trade walk as buys at the wallet's true auction cost, so
  * bidders never show zero buys. Tokens sold beyond tracked inventory
- * (transfers in) carry a zero basis — with the full history and explicit
- * claims in hand, an unexplained inflow is a transfer, not a hidden buy —
- * and flag transferred_in.
+ * (transfers in) entered the wallet outside the swap tape — with the full
+ * history and explicit claims in hand, an unexplained inflow is a transfer,
+ * not a hidden buy — so the wallet's basis is UNKNOWN (not $0) and the row
+ * flags transferred_in.
+ *
+ * UNKNOWN-BASIS ROWS: when the server cannot compute a wallet's basis — the
+ * wallet transferred tokens in (transferred_in), or its auction spend was
+ * not USD-convertible — basis_unknown is true and the four basis-derived
+ * money fields (cost_basis_usd, avg_cost_usd, realized_pnl_usd,
+ * unrealized_pnl_usd) are served as 0 and MUST be read as "unknown", never
+ * as a real $0.00. Such wallets rank strictly after every computable-PnL
+ * row — including loss-makers: an unknown 0 never outranks a real figure —
+ * so a transfer-in whale's raw proceeds can never crowd real traders out
+ * of the request limit. Observed figures (buys/sells/proceeds/tokens) are
+ * always set and always truthful. unrealized_pnl_unknown additionally
+ * covers the basis-known wallet whose unrealized leg alone is uncomputable
+ * (token has no spot price). (These are flags rather than proto3 `optional`
+ * on the money fields because changing an existing field's presence is a
+ * breaking gencode change for published clients.)
  *
  * @generated from message data.v2.TokenTopTrader
  */
@@ -2028,19 +2044,23 @@ export class TokenTopTrader extends Message {
         this.remainingTokens = 0;
         /**
          * USD cost basis of the REMAINING position: grows with buys/claims,
-         * shrinks by average cost × amount on every sell.
+         * shrinks by average cost × amount on every sell. Meaningless (served 0)
+         * when basis_unknown — read that as "unknown", not a zero basis.
          *
          * @generated from field: double cost_basis_usd = 9;
          */
         this.costBasisUsd = 0;
         /**
-         * cost_basis_usd ÷ remaining_tokens; 0 for wallets holding nothing (or
-         * with no tracked basis).
+         * cost_basis_usd ÷ remaining_tokens; 0 for wallets holding nothing.
+         * Meaningless (served 0) when basis_unknown.
          *
          * @generated from field: double avg_cost_usd = 10;
          */
         this.avgCostUsd = 0;
         /**
+         * Meaningless (served 0) when basis_unknown — proceeds booked against an
+         * unknowable basis are not a PnL; such rows rank as realized 0.
+         *
          * @generated from field: double realized_pnl_usd = 11;
          */
         this.realizedPnlUsd = 0;
@@ -2062,20 +2082,39 @@ export class TokenTopTrader extends Message {
         /**
          * Mark-to-market PnL of the remaining position at the token's latest
          * known price: remaining_tokens × (spot − avg_cost_usd). The documented
-         * ranking tiebreak, served so clients can render it.
+         * ranking tiebreak, served so clients can render it. Meaningless (served
+         * 0) when unrealized_pnl_unknown — basis unknown, or no known spot price.
          *
          * @generated from field: double unrealized_pnl_usd = 14;
          */
         this.unrealizedPnlUsd = 0;
         /**
          * True when the wallet sold beyond its tracked inventory at least once —
-         * the excess entered the wallet outside the swap tape (a transfer in)
-         * and carries a zero basis. Distinguishes a genuine transfer from a
-         * data gap when cost_basis_usd is 0.
+         * the excess entered the wallet outside the swap tape (a transfer in),
+         * so its basis is unknown. Always implies basis_unknown.
          *
          * @generated from field: bool transferred_in = 15;
          */
         this.transferredIn = false;
+        /**
+         * True when the wallet's basis could not be computed — it transferred
+         * tokens in (transferred_in), or its auction spend was not
+         * USD-convertible. Clients should render the four basis-derived money
+         * fields as unknown ("–"), not $0.00; the row ranks after every
+         * computable-PnL row (see message doc). Implies unrealized_pnl_unknown.
+         *
+         * @generated from field: bool basis_unknown = 16;
+         */
+        this.basisUnknown = false;
+        /**
+         * True when unrealized_pnl_usd alone is not computable: basis_unknown, or
+         * the token has no known spot price (a missing spot must not read as a
+         * total loss). Served 0 then — render unknown ("–"), not $0.00. The other
+         * money fields stay real when basis_unknown is false.
+         *
+         * @generated from field: bool unrealized_pnl_unknown = 17;
+         */
+        this.unrealizedPnlUnknown = false;
         proto3.util.initPartial(data, this);
     }
     static fromBinary(bytes, options) {
@@ -2109,6 +2148,8 @@ TokenTopTrader.fields = proto3.util.newFieldList(() => [
     { no: 13, name: "has_claims", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
     { no: 14, name: "unrealized_pnl_usd", kind: "scalar", T: 1 /* ScalarType.DOUBLE */ },
     { no: 15, name: "transferred_in", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
+    { no: 16, name: "basis_unknown", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
+    { no: 17, name: "unrealized_pnl_unknown", kind: "scalar", T: 8 /* ScalarType.BOOL */ },
 ]);
 /**
  * @generated from message data.v2.GetTokenTopTradersResponse
@@ -2118,8 +2159,12 @@ export class GetTokenTopTradersResponse extends Message {
         super();
         /**
          * Ranked realized PnL desc, unrealized PnL desc as the tiebreak (orders
-         * never-sold claimers sensibly — all realized 0), capped at the request
-         * limit. Only wallets with at least one trade or claim appear.
+         * never-sold claimers sensibly — all realized 0), wallet address asc as
+         * the final key, capped at the request limit. Unknown-basis rows
+         * (transferred_in, or an inconvertible auction spend) partition strictly
+         * after every computable-PnL row, including losses — so they cannot
+         * consume top slots on raw proceeds or displace losing traders. Only
+         * wallets with at least one trade or claim appear.
          *
          * @generated from field: repeated data.v2.TokenTopTrader traders = 1;
          */

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@uniswap/client-data-api",
-    "version": "0.0.168",
+    "version": "0.0.170",
     "publishConfig": {
       "access": "public"
     },