@taphubhq/sdk-core 0.16.2 → 0.17.1

package/dist/index.cjs

@@ -139,7 +139,7 @@ function normaliseAgencyPairs(rows) {
     });
   }
   return rows.map((row) => ({
-    gamePairId: row.gamePairId,
+    pairId: row.pairId,
     pair: row.pair,
     thumb: row.thumb,
     ordering: Number(row.ordering),
@@ -153,7 +153,7 @@ function normaliseAgencyPairs(rows) {
 // src/modules/agencyPair/queries.ts
 var FETCH_AGENCY_PAIRS_QUERY = `query FetchAgencyPairs($filter: AgencyPairFilter) {
   fetchAgencyPairs(filter: $filter) {
-    gamePairId pair thumb ordering status maxCoef currentPrice currentVol24h
+    pairId pair thumb ordering status maxCoef currentPrice currentVol24h
   }
 }`;
 
@@ -479,8 +479,8 @@ var PLACE_BID_MUTATION = `mutation PlaceBid($input: PlaceBidInput!) {
     id user_id game_id currency amount coefficient time1 time2 price1 price2 status payout slippage created_at
   }
 }`;
-var MY_BIDS_QUERY = `query MyBids($statuses: [BidStatus!], $limit: Int, $offset: Int, $gameId: ID) {
-  myBids(statuses: $statuses, limit: $limit, offset: $offset, gameId: $gameId) {
+var MY_BIDS_QUERY = `query MyBids($statuses: [BidStatus!], $limit: Int, $offset: Int, $pairId: ID) {
+  myBids(statuses: $statuses, limit: $limit, offset: $offset, pairId: $pairId) {
     id user_id game_id currency amount coefficient time1 time2 price1 price2 status payout slippage created_at
   }
 }`;
@@ -508,7 +508,9 @@ var BidModule = class {
   async placeBid(input, opts) {
     const variables = {
       input: {
-        game_id: input.gameId,
+        // REVIEW[bid-260602-v2]: input field pairId (was: game_id) — the #2 game_pairs.id.
+        // Server composes the agencyPairId composite and stores it in bids.game_id (frozen).
+        pairId: input.pairId,
         // wallet_id is forwarded as-is — grid-api enforces ownership +
         // currency validation. See openspec/bid-260518-wallet-id D1/D8.
         wallet_id: input.walletId,
@@ -532,7 +534,7 @@ var BidModule = class {
       if (err instanceof TaphubValidationError && err.code === "NotExist") {
         throw new TaphubValidationError("Game not found", {
           code: "GameNotFound",
-          details: { gameId: input.gameId }
+          details: { pairId: input.pairId }
         });
       }
       throw err;
@@ -563,8 +565,8 @@ var BidModule = class {
     if (opts?.offset !== void 0) {
       variables.offset = opts.offset;
     }
-    if (opts?.gameId !== void 0) {
-      variables.gameId = opts.gameId;
+    if (opts?.pairId !== void 0) {
+      variables.pairId = opts.pairId;
     }
     const body = await this.#graphql.request(
       MY_BIDS_QUERY,
@@ -794,8 +796,8 @@ function normalisePairInfo(node) {
 }
 
 // src/modules/pair/queries.ts
-var PAIR_QUERY = `query Pair($pair: String!, $gameplaySlug: String) {
-  pair(pair: $pair, gameplaySlug: $gameplaySlug) {
+var PAIR_QUERY = `query Pair($pairId: ID!) {
+  pair(pairId: $pairId) {
     id pair status created_at
     config {
       gridConfig { cellSizeTime cellSizeValue candleSize baseline baselineTime }
@@ -804,8 +806,8 @@ var PAIR_QUERY = `query Pair($pair: String!, $gameplaySlug: String) {
     }
   }
 }`;
-var CHART_HISTORY_QUERY = `query ChartHistory($agencyPairId: ID!, $limit: Int) {
-  chartHistory(agencyPairId: $agencyPairId, limit: $limit) {
+var CHART_HISTORY_QUERY = `query ChartHistory($pairId: ID!, $limit: Int) {
+  chartHistory(pairId: $pairId, limit: $limit) {
     time o h l c volatility coefMults
   }
 }`;
@@ -826,9 +828,11 @@ var PairModule = class {
   constructor(deps) {
     this.#graphql = deps.graphql;
   }
-  async get(pair, opts) {
-    const variables = { pair };
-    if (opts?.gameplaySlug) variables.gameplaySlug = opts.gameplaySlug;
+  // REVIEW[bid-260602-v2]: keyed by pairId (the #2 game_pairs.id, e.g. "grid-ETH-USD").
+  // Dropped the `pair` symbol arg + `gameplaySlug` option — the gameplay is already
+  // encoded in pairId, and the server composes agencyPairId from agency context.
+  async get(pairId, opts) {
+    const variables = { pairId };
     let body;
     try {
       body = await this.#graphql.request(PAIR_QUERY, variables, opts);
@@ -836,7 +840,7 @@ var PairModule = class {
       if (err instanceof TaphubValidationError && err.code === "NotExist") {
         throw new TaphubValidationError("Game not found for pair", {
           code: "GameNotFound",
-          details: { pair }
+          details: { pairId }
         });
       }
       throw err;
@@ -844,7 +848,7 @@ var PairModule = class {
     if (body.pair === null) {
       throw new TaphubValidationError("Game not found for pair", {
         code: "GameNotFound",
-        details: { pair }
+        details: { pairId }
       });
     }
     return normalisePair(body.pair);
@@ -857,8 +861,8 @@ var PairModule = class {
    *
    * @example
    * const pairs = await client.pair.availableGamePairs({ gameplayId: 'taptrading' });
-   * const game  = await client.pair.get(pairs[0].pair, { gameplaySlug: pairs[0].gameplayId });
-   * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? game.id, userId);
+   * const pair  = await client.pair.get(pairs[0].id);
+   * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? pair.id, userId);
    */
   async availableGamePairs(opts) {
     const variables = {};
@@ -870,9 +874,9 @@ var PairModule = class {
     );
     return body.builderAvailableGamePairs.map(normalisePairInfo);
   }
-  // REVIEW[bid-260602]: chartHistory param/variable renamed agencyPairId (was: gameId)
-  async chartHistory(agencyPairId, limit, opts) {
-    const variables = { agencyPairId };
+  // REVIEW[bid-260602-v2]: chartHistory param/variable renamed pairId (was: agencyPairId/gameId)
+  async chartHistory(pairId, limit, opts) {
+    const variables = { pairId };
     if (limit !== void 0) {
       variables.limit = limit;
     }
@@ -899,17 +903,18 @@ var USER_SCOPED_SUFFIXES = ["bid_result", "balance_update"];
 var TOPIC_PREFIX = "game";
 var MARKET_TOPIC_PREFIX = "market";
 var WALLET_TOPIC_PREFIX = "wallet";
+var PUBLIC_PREFIX = "public";
 function walletBalanceTopic(userId) {
   return `${WALLET_TOPIC_PREFIX}/users/${userId}/balance`;
 }
-function agencyPairStatsTopic(aid, gamePairId) {
-  return `public/agency/${aid}/pair/${gamePairId}/stats`;
+function agencyPairStatsTopic(aid, pairId) {
+  return `public/agency/${aid}/pair/${pairId}/stats`;
 }
 function topicFor(gameId, suffix, userId) {
   if (USER_SCOPED_SUFFIXES.includes(suffix)) {
     return `${TOPIC_PREFIX}/${gameId}/user/${userId}/${suffix}`;
   }
-  return `${TOPIC_PREFIX}/${gameId}/${suffix}`;
+  return `${PUBLIC_PREFIX}/${TOPIC_PREFIX}/${gameId}/${suffix}`;
 }
 function normaliseUserId(userId) {
   return userId && userId !== "" ? userId : null;
@@ -1063,28 +1068,28 @@ function createMqttTransport(endpoint, opts = {}) {
         mqttClient.subscribe(t, { qos: 1 });
       }
     },
-    subscribeCandle(pair, onCandle) {
-      const topic = `${MARKET_TOPIC_PREFIX}/${pair.replace(/\//g, "_")}/candle`;
-      if (candleSubscriptions.has(pair)) return;
+    subscribeCandle(pairId, onCandle) {
+      const topic = `${PUBLIC_PREFIX}/${MARKET_TOPIC_PREFIX}/${pairId}/candle`;
+      if (candleSubscriptions.has(pairId)) return;
       const mqttClient = ensureConnected();
-      candleSubscriptions.set(pair, { topic, onCandle });
+      candleSubscriptions.set(pairId, { topic, onCandle });
       mqttClient.subscribe(topic, { qos: 0 });
     },
-    unsubscribeCandle(pair) {
-      const entry = candleSubscriptions.get(pair);
+    unsubscribeCandle(pairId) {
+      const entry = candleSubscriptions.get(pairId);
       if (!entry) return;
       if (client) client.unsubscribe(entry.topic);
-      candleSubscriptions.delete(pair);
+      candleSubscriptions.delete(pairId);
     },
-    subscribeAgencyPairStats(aid, gamePairId, onStats) {
-      const topic = agencyPairStatsTopic(aid, gamePairId);
+    subscribeAgencyPairStats(aid, pairId, onStats) {
+      const topic = agencyPairStatsTopic(aid, pairId);
       if (statsSubscriptions.has(topic)) return;
       const mqttClient = ensureConnected();
       statsSubscriptions.set(topic, { topic, onStats });
       mqttClient.subscribe(topic, { qos: 0 });
     },
-    unsubscribeAgencyPairStats(aid, gamePairId) {
-      const topic = agencyPairStatsTopic(aid, gamePairId);
+    unsubscribeAgencyPairStats(aid, pairId) {
+      const topic = agencyPairStatsTopic(aid, pairId);
       const entry = statsSubscriptions.get(topic);
       if (!entry) return;
       if (client) client.unsubscribe(entry.topic);
@@ -1420,22 +1425,25 @@ var RealtimeModule = class extends import_eventemitter33.default {
     this.#transport.unsubscribeWallet(cleanUserId);
   }
   /**
-   * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
-   * Independent of game/agency — candle is market-wide public data.
+   * Subscribe to public market candle data for a pair, keyed by pairId
+   * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
+   * candle is market-wide public data.
    */
-  subscribeCandle(pair, onCandle) {
-    this.#transport.subscribeCandle(pair, onCandle);
+  // REVIEW[bid-260602-v2]: param pairId (was: pair) — slash-free #2 game_pairs.id.
+  subscribeCandle(pairId, onCandle) {
+    this.#transport.subscribeCandle(pairId, onCandle);
   }
-  /** Unsubscribe from candle data for a pair. */
-  unsubscribeCandle(pair) {
-    this.#transport.unsubscribeCandle(pair);
+  /** Unsubscribe from candle data for a pairId. */
+  unsubscribeCandle(pairId) {
+    this.#transport.unsubscribeCandle(pairId);
   }
   /**
    * Subscribe to the live per-pair stats stream for the client's own agency.
    * Scoped to the agency the client was constructed with — there is no argument
    * to target another agency by design.
    */
-  subscribeAgencyPairStats(gamePairId, handler) {
+  // REVIEW[bid-260602-v2]: param pairId (was: gamePairId) — the #2 game_pairs.id.
+  subscribeAgencyPairStats(pairId, handler) {
     if (!this.#agencyId) {
       throw new TaphubError("agencyId is required to subscribe to agency pair stats", {
         code: "AgencyIdRequired"
@@ -1450,12 +1458,13 @@ var RealtimeModule = class extends import_eventemitter33.default {
         ts: Number(p.ts)
       });
     };
-    this.#transport.subscribeAgencyPairStats(this.#agencyId, gamePairId, onStats);
+    this.#transport.subscribeAgencyPairStats(this.#agencyId, pairId, onStats);
   }
   /** Unsubscribe from the per-pair stats stream for the client's own agency. */
-  unsubscribeAgencyPairStats(gamePairId) {
+  // REVIEW[bid-260602-v2]: param pairId (was: gamePairId).
+  unsubscribeAgencyPairStats(pairId) {
     if (!this.#agencyId) return;
-    this.#transport.unsubscribeAgencyPairStats(this.#agencyId, gamePairId);
+    this.#transport.unsubscribeAgencyPairStats(this.#agencyId, pairId);
   }
   disconnect() {
     for (const entry of this.#entries.values()) {

package/dist/index.d.mts

@@ -71,8 +71,8 @@ interface AgencyPairFilter {
     status?: AgencyPairStatus;
 }
 interface AgencyPairStats {
-    /** game_pairs.id slug, e.g. "grid-ETH-USD". Use to build the stats MQTT topic. */
-    gamePairId: string;
+    /** game_pairs.id, e.g. "grid-ETH-USD". Use to build the stats MQTT topic. */
+    pairId: string;
     /** Display name, e.g. "ETH/USD". */
     pair: string;
     /** Icon URL. */
@@ -186,7 +186,7 @@ interface CancelBidResult {
     newBalance: string;
 }
 interface PlaceBidInput {
-    gameId: string;
+    pairId: string;
     /**
      * UUID of the user's wallet to debit. Required (non-optional) since
      * grid-api's `PlaceBidInput.wallet_id` is NON_NULL (`ID!`). The SDK stays
@@ -230,7 +230,7 @@ declare class BidModule {
         statuses?: BidStatus[];
         limit?: number;
         offset?: number;
-        gameId?: string;
+        pairId?: string;
         signal?: AbortSignal;
     }): Promise<Bid[]>;
 }
@@ -405,8 +405,7 @@ interface PairModuleDeps {
 declare class PairModule {
     #private;
     constructor(deps: PairModuleDeps);
-    get(pair: string, opts?: {
-        gameplaySlug?: string;
+    get(pairId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<Pair>;
     /**
@@ -417,14 +416,14 @@ declare class PairModule {
      *
      * @example
      * const pairs = await client.pair.availableGamePairs({ gameplayId: 'taptrading' });
-     * const game  = await client.pair.get(pairs[0].pair, { gameplaySlug: pairs[0].gameplayId });
-     * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? game.id, userId);
+     * const pair  = await client.pair.get(pairs[0].id);
+     * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? pair.id, userId);
      */
     availableGamePairs(opts?: {
         gameplayId?: string;
         signal?: AbortSignal;
     }): Promise<PairInfo[]>;
-    chartHistory(agencyPairId: string, limit?: number, opts?: {
+    chartHistory(pairId: string, limit?: number, opts?: {
         signal?: AbortSignal;
     }): Promise<Candle[]>;
 }
@@ -538,22 +537,23 @@ interface MqttTransport {
      */
     unsubscribeAll(gameId: string, userId?: string | null): void;
     /**
-     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
-     * Independent of game/agency context — candle is market-wide public data.
-     * Idempotent: multiple calls for the same pair are deduplicated.
+     * Subscribe to public market candle data for a pair, keyed by pairId
+     * (the slash-free #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of
+     * game/agency context — candle is market-wide public data.
+     * Idempotent: multiple calls for the same pairId are deduplicated.
      */
-    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
-    /** Tear down the candle subscription for a pair. */
-    unsubscribeCandle(pair: string): void;
+    subscribeCandle(pairId: string, onCandle: MqttCandleHandler): void;
+    /** Tear down the candle subscription for a pairId. */
+    unsubscribeCandle(pairId: string): void;
     /**
      * Subscribe to the public per-pair stats stream for an agency, topic
-     * `public/agency/{aid}/pair/{gamePairId}/stats`. `aid` and `gamePairId` are
-     * used raw (no slash escaping) to byte-match the backend publisher.
-     * Idempotent: multiple calls for the same `(aid, gamePairId)` are deduplicated.
+     * `public/agency/{aid}/pair/{pairId}/stats`. `aid` and `pairId` are used raw
+     * (no slash escaping — pairId is slash-free) to byte-match the backend publisher.
+     * Idempotent: multiple calls for the same `(aid, pairId)` are deduplicated.
      */
-    subscribeAgencyPairStats(aid: string, gamePairId: string, onStats: MqttAgencyPairStatsHandler): void;
-    /** Tear down the stats subscription for an `(aid, gamePairId)`. */
-    unsubscribeAgencyPairStats(aid: string, gamePairId: string): void;
+    subscribeAgencyPairStats(aid: string, pairId: string, onStats: MqttAgencyPairStatsHandler): void;
+    /** Tear down the stats subscription for an `(aid, pairId)`. */
+    unsubscribeAgencyPairStats(aid: string, pairId: string): void;
     /**
      * Subscribe to the user-scoped wallet balance stream, topic
      * `wallet/users/{userId}/balance`. Independent of any game subscription — NOT
@@ -667,7 +667,7 @@ interface MqttIdealConfigEvent {
 }
 /**
  * Live per-pair stats tick from the public stream
- * `public/agency/{aid}/pair/{gamePairId}/stats`. The backend suppresses
+ * `public/agency/{aid}/pair/{pairId}/stats`. The backend suppresses
  * unchanged ticks, so a subscriber may not receive an event until price or
  * vol24h actually moves — seed initial values from `agencyPairs.list()`.
  */
@@ -755,20 +755,21 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
      */
     unsubscribeWallet(userId: string): void;
     /**
-     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
-     * Independent of game/agency — candle is market-wide public data.
+     * Subscribe to public market candle data for a pair, keyed by pairId
+     * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
+     * candle is market-wide public data.
      */
-    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
-    /** Unsubscribe from candle data for a pair. */
-    unsubscribeCandle(pair: string): void;
+    subscribeCandle(pairId: string, onCandle: MqttCandleHandler): void;
+    /** Unsubscribe from candle data for a pairId. */
+    unsubscribeCandle(pairId: string): void;
     /**
      * Subscribe to the live per-pair stats stream for the client's own agency.
      * Scoped to the agency the client was constructed with — there is no argument
      * to target another agency by design.
      */
-    subscribeAgencyPairStats(gamePairId: string, handler: (event: MqttAgencyPairStatsEvent) => void): void;
+    subscribeAgencyPairStats(pairId: string, handler: (event: MqttAgencyPairStatsEvent) => void): void;
     /** Unsubscribe from the per-pair stats stream for the client's own agency. */
-    unsubscribeAgencyPairStats(gamePairId: string): void;
+    unsubscribeAgencyPairStats(pairId: string): void;
     disconnect(): void;
 }
 

package/dist/index.d.ts

@@ -71,8 +71,8 @@ interface AgencyPairFilter {
     status?: AgencyPairStatus;
 }
 interface AgencyPairStats {
-    /** game_pairs.id slug, e.g. "grid-ETH-USD". Use to build the stats MQTT topic. */
-    gamePairId: string;
+    /** game_pairs.id, e.g. "grid-ETH-USD". Use to build the stats MQTT topic. */
+    pairId: string;
     /** Display name, e.g. "ETH/USD". */
     pair: string;
     /** Icon URL. */
@@ -186,7 +186,7 @@ interface CancelBidResult {
     newBalance: string;
 }
 interface PlaceBidInput {
-    gameId: string;
+    pairId: string;
     /**
      * UUID of the user's wallet to debit. Required (non-optional) since
      * grid-api's `PlaceBidInput.wallet_id` is NON_NULL (`ID!`). The SDK stays
@@ -230,7 +230,7 @@ declare class BidModule {
         statuses?: BidStatus[];
         limit?: number;
         offset?: number;
-        gameId?: string;
+        pairId?: string;
         signal?: AbortSignal;
     }): Promise<Bid[]>;
 }
@@ -405,8 +405,7 @@ interface PairModuleDeps {
 declare class PairModule {
     #private;
     constructor(deps: PairModuleDeps);
-    get(pair: string, opts?: {
-        gameplaySlug?: string;
+    get(pairId: string, opts?: {
         signal?: AbortSignal;
     }): Promise<Pair>;
     /**
@@ -417,14 +416,14 @@ declare class PairModule {
      *
      * @example
      * const pairs = await client.pair.availableGamePairs({ gameplayId: 'taptrading' });
-     * const game  = await client.pair.get(pairs[0].pair, { gameplaySlug: pairs[0].gameplayId });
-     * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? game.id, userId);
+     * const pair  = await client.pair.get(pairs[0].id);
+     * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? pair.id, userId);
      */
     availableGamePairs(opts?: {
         gameplayId?: string;
         signal?: AbortSignal;
     }): Promise<PairInfo[]>;
-    chartHistory(agencyPairId: string, limit?: number, opts?: {
+    chartHistory(pairId: string, limit?: number, opts?: {
         signal?: AbortSignal;
     }): Promise<Candle[]>;
 }
@@ -538,22 +537,23 @@ interface MqttTransport {
      */
     unsubscribeAll(gameId: string, userId?: string | null): void;
     /**
-     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
-     * Independent of game/agency context — candle is market-wide public data.
-     * Idempotent: multiple calls for the same pair are deduplicated.
+     * Subscribe to public market candle data for a pair, keyed by pairId
+     * (the slash-free #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of
+     * game/agency context — candle is market-wide public data.
+     * Idempotent: multiple calls for the same pairId are deduplicated.
      */
-    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
-    /** Tear down the candle subscription for a pair. */
-    unsubscribeCandle(pair: string): void;
+    subscribeCandle(pairId: string, onCandle: MqttCandleHandler): void;
+    /** Tear down the candle subscription for a pairId. */
+    unsubscribeCandle(pairId: string): void;
     /**
      * Subscribe to the public per-pair stats stream for an agency, topic
-     * `public/agency/{aid}/pair/{gamePairId}/stats`. `aid` and `gamePairId` are
-     * used raw (no slash escaping) to byte-match the backend publisher.
-     * Idempotent: multiple calls for the same `(aid, gamePairId)` are deduplicated.
+     * `public/agency/{aid}/pair/{pairId}/stats`. `aid` and `pairId` are used raw
+     * (no slash escaping — pairId is slash-free) to byte-match the backend publisher.
+     * Idempotent: multiple calls for the same `(aid, pairId)` are deduplicated.
      */
-    subscribeAgencyPairStats(aid: string, gamePairId: string, onStats: MqttAgencyPairStatsHandler): void;
-    /** Tear down the stats subscription for an `(aid, gamePairId)`. */
-    unsubscribeAgencyPairStats(aid: string, gamePairId: string): void;
+    subscribeAgencyPairStats(aid: string, pairId: string, onStats: MqttAgencyPairStatsHandler): void;
+    /** Tear down the stats subscription for an `(aid, pairId)`. */
+    unsubscribeAgencyPairStats(aid: string, pairId: string): void;
     /**
      * Subscribe to the user-scoped wallet balance stream, topic
      * `wallet/users/{userId}/balance`. Independent of any game subscription — NOT
@@ -667,7 +667,7 @@ interface MqttIdealConfigEvent {
 }
 /**
  * Live per-pair stats tick from the public stream
- * `public/agency/{aid}/pair/{gamePairId}/stats`. The backend suppresses
+ * `public/agency/{aid}/pair/{pairId}/stats`. The backend suppresses
  * unchanged ticks, so a subscriber may not receive an event until price or
  * vol24h actually moves — seed initial values from `agencyPairs.list()`.
  */
@@ -755,20 +755,21 @@ declare class RealtimeModule extends EventEmitter<RealtimeModuleEvents> {
      */
     unsubscribeWallet(userId: string): void;
     /**
-     * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
-     * Independent of game/agency — candle is market-wide public data.
+     * Subscribe to public market candle data for a pair, keyed by pairId
+     * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
+     * candle is market-wide public data.
      */
-    subscribeCandle(pair: string, onCandle: MqttCandleHandler): void;
-    /** Unsubscribe from candle data for a pair. */
-    unsubscribeCandle(pair: string): void;
+    subscribeCandle(pairId: string, onCandle: MqttCandleHandler): void;
+    /** Unsubscribe from candle data for a pairId. */
+    unsubscribeCandle(pairId: string): void;
     /**
      * Subscribe to the live per-pair stats stream for the client's own agency.
      * Scoped to the agency the client was constructed with — there is no argument
      * to target another agency by design.
      */
-    subscribeAgencyPairStats(gamePairId: string, handler: (event: MqttAgencyPairStatsEvent) => void): void;
+    subscribeAgencyPairStats(pairId: string, handler: (event: MqttAgencyPairStatsEvent) => void): void;
     /** Unsubscribe from the per-pair stats stream for the client's own agency. */
-    unsubscribeAgencyPairStats(gamePairId: string): void;
+    unsubscribeAgencyPairStats(pairId: string): void;
     disconnect(): void;
 }
 

package/dist/index.js

@@ -74,7 +74,7 @@ function normaliseAgencyPairs(rows) {
     });
   }
   return rows.map((row) => ({
-    gamePairId: row.gamePairId,
+    pairId: row.pairId,
     pair: row.pair,
     thumb: row.thumb,
     ordering: Number(row.ordering),
@@ -88,7 +88,7 @@ function normaliseAgencyPairs(rows) {
 // src/modules/agencyPair/queries.ts
 var FETCH_AGENCY_PAIRS_QUERY = `query FetchAgencyPairs($filter: AgencyPairFilter) {
   fetchAgencyPairs(filter: $filter) {
-    gamePairId pair thumb ordering status maxCoef currentPrice currentVol24h
+    pairId pair thumb ordering status maxCoef currentPrice currentVol24h
   }
 }`;
 
@@ -414,8 +414,8 @@ var PLACE_BID_MUTATION = `mutation PlaceBid($input: PlaceBidInput!) {
     id user_id game_id currency amount coefficient time1 time2 price1 price2 status payout slippage created_at
   }
 }`;
-var MY_BIDS_QUERY = `query MyBids($statuses: [BidStatus!], $limit: Int, $offset: Int, $gameId: ID) {
-  myBids(statuses: $statuses, limit: $limit, offset: $offset, gameId: $gameId) {
+var MY_BIDS_QUERY = `query MyBids($statuses: [BidStatus!], $limit: Int, $offset: Int, $pairId: ID) {
+  myBids(statuses: $statuses, limit: $limit, offset: $offset, pairId: $pairId) {
     id user_id game_id currency amount coefficient time1 time2 price1 price2 status payout slippage created_at
   }
 }`;
@@ -443,7 +443,9 @@ var BidModule = class {
   async placeBid(input, opts) {
     const variables = {
       input: {
-        game_id: input.gameId,
+        // REVIEW[bid-260602-v2]: input field pairId (was: game_id) — the #2 game_pairs.id.
+        // Server composes the agencyPairId composite and stores it in bids.game_id (frozen).
+        pairId: input.pairId,
         // wallet_id is forwarded as-is — grid-api enforces ownership +
         // currency validation. See openspec/bid-260518-wallet-id D1/D8.
         wallet_id: input.walletId,
@@ -467,7 +469,7 @@ var BidModule = class {
       if (err instanceof TaphubValidationError && err.code === "NotExist") {
         throw new TaphubValidationError("Game not found", {
           code: "GameNotFound",
-          details: { gameId: input.gameId }
+          details: { pairId: input.pairId }
         });
       }
       throw err;
@@ -498,8 +500,8 @@ var BidModule = class {
     if (opts?.offset !== void 0) {
       variables.offset = opts.offset;
     }
-    if (opts?.gameId !== void 0) {
-      variables.gameId = opts.gameId;
+    if (opts?.pairId !== void 0) {
+      variables.pairId = opts.pairId;
     }
     const body = await this.#graphql.request(
       MY_BIDS_QUERY,
@@ -729,8 +731,8 @@ function normalisePairInfo(node) {
 }
 
 // src/modules/pair/queries.ts
-var PAIR_QUERY = `query Pair($pair: String!, $gameplaySlug: String) {
-  pair(pair: $pair, gameplaySlug: $gameplaySlug) {
+var PAIR_QUERY = `query Pair($pairId: ID!) {
+  pair(pairId: $pairId) {
     id pair status created_at
     config {
       gridConfig { cellSizeTime cellSizeValue candleSize baseline baselineTime }
@@ -739,8 +741,8 @@ var PAIR_QUERY = `query Pair($pair: String!, $gameplaySlug: String) {
     }
   }
 }`;
-var CHART_HISTORY_QUERY = `query ChartHistory($agencyPairId: ID!, $limit: Int) {
-  chartHistory(agencyPairId: $agencyPairId, limit: $limit) {
+var CHART_HISTORY_QUERY = `query ChartHistory($pairId: ID!, $limit: Int) {
+  chartHistory(pairId: $pairId, limit: $limit) {
     time o h l c volatility coefMults
   }
 }`;
@@ -761,9 +763,11 @@ var PairModule = class {
   constructor(deps) {
     this.#graphql = deps.graphql;
   }
-  async get(pair, opts) {
-    const variables = { pair };
-    if (opts?.gameplaySlug) variables.gameplaySlug = opts.gameplaySlug;
+  // REVIEW[bid-260602-v2]: keyed by pairId (the #2 game_pairs.id, e.g. "grid-ETH-USD").
+  // Dropped the `pair` symbol arg + `gameplaySlug` option — the gameplay is already
+  // encoded in pairId, and the server composes agencyPairId from agency context.
+  async get(pairId, opts) {
+    const variables = { pairId };
     let body;
     try {
       body = await this.#graphql.request(PAIR_QUERY, variables, opts);
@@ -771,7 +775,7 @@ var PairModule = class {
       if (err instanceof TaphubValidationError && err.code === "NotExist") {
         throw new TaphubValidationError("Game not found for pair", {
           code: "GameNotFound",
-          details: { pair }
+          details: { pairId }
         });
       }
       throw err;
@@ -779,7 +783,7 @@ var PairModule = class {
     if (body.pair === null) {
       throw new TaphubValidationError("Game not found for pair", {
         code: "GameNotFound",
-        details: { pair }
+        details: { pairId }
       });
     }
     return normalisePair(body.pair);
@@ -792,8 +796,8 @@ var PairModule = class {
    *
    * @example
    * const pairs = await client.pair.availableGamePairs({ gameplayId: 'taptrading' });
-   * const game  = await client.pair.get(pairs[0].pair, { gameplaySlug: pairs[0].gameplayId });
-   * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? game.id, userId);
+   * const pair  = await client.pair.get(pairs[0].id);
+   * const ch    = client.realtime?.subscribe(pairs[0].agencyPairId ?? pair.id, userId);
    */
   async availableGamePairs(opts) {
     const variables = {};
@@ -805,9 +809,9 @@ var PairModule = class {
     );
     return body.builderAvailableGamePairs.map(normalisePairInfo);
   }
-  // REVIEW[bid-260602]: chartHistory param/variable renamed agencyPairId (was: gameId)
-  async chartHistory(agencyPairId, limit, opts) {
-    const variables = { agencyPairId };
+  // REVIEW[bid-260602-v2]: chartHistory param/variable renamed pairId (was: agencyPairId/gameId)
+  async chartHistory(pairId, limit, opts) {
+    const variables = { pairId };
     if (limit !== void 0) {
       variables.limit = limit;
     }
@@ -834,17 +838,18 @@ var USER_SCOPED_SUFFIXES = ["bid_result", "balance_update"];
 var TOPIC_PREFIX = "game";
 var MARKET_TOPIC_PREFIX = "market";
 var WALLET_TOPIC_PREFIX = "wallet";
+var PUBLIC_PREFIX = "public";
 function walletBalanceTopic(userId) {
   return `${WALLET_TOPIC_PREFIX}/users/${userId}/balance`;
 }
-function agencyPairStatsTopic(aid, gamePairId) {
-  return `public/agency/${aid}/pair/${gamePairId}/stats`;
+function agencyPairStatsTopic(aid, pairId) {
+  return `public/agency/${aid}/pair/${pairId}/stats`;
 }
 function topicFor(gameId, suffix, userId) {
   if (USER_SCOPED_SUFFIXES.includes(suffix)) {
     return `${TOPIC_PREFIX}/${gameId}/user/${userId}/${suffix}`;
   }
-  return `${TOPIC_PREFIX}/${gameId}/${suffix}`;
+  return `${PUBLIC_PREFIX}/${TOPIC_PREFIX}/${gameId}/${suffix}`;
 }
 function normaliseUserId(userId) {
   return userId && userId !== "" ? userId : null;
@@ -998,28 +1003,28 @@ function createMqttTransport(endpoint, opts = {}) {
         mqttClient.subscribe(t, { qos: 1 });
       }
     },
-    subscribeCandle(pair, onCandle) {
-      const topic = `${MARKET_TOPIC_PREFIX}/${pair.replace(/\//g, "_")}/candle`;
-      if (candleSubscriptions.has(pair)) return;
+    subscribeCandle(pairId, onCandle) {
+      const topic = `${PUBLIC_PREFIX}/${MARKET_TOPIC_PREFIX}/${pairId}/candle`;
+      if (candleSubscriptions.has(pairId)) return;
       const mqttClient = ensureConnected();
-      candleSubscriptions.set(pair, { topic, onCandle });
+      candleSubscriptions.set(pairId, { topic, onCandle });
       mqttClient.subscribe(topic, { qos: 0 });
     },
-    unsubscribeCandle(pair) {
-      const entry = candleSubscriptions.get(pair);
+    unsubscribeCandle(pairId) {
+      const entry = candleSubscriptions.get(pairId);
       if (!entry) return;
       if (client) client.unsubscribe(entry.topic);
-      candleSubscriptions.delete(pair);
+      candleSubscriptions.delete(pairId);
     },
-    subscribeAgencyPairStats(aid, gamePairId, onStats) {
-      const topic = agencyPairStatsTopic(aid, gamePairId);
+    subscribeAgencyPairStats(aid, pairId, onStats) {
+      const topic = agencyPairStatsTopic(aid, pairId);
       if (statsSubscriptions.has(topic)) return;
       const mqttClient = ensureConnected();
       statsSubscriptions.set(topic, { topic, onStats });
       mqttClient.subscribe(topic, { qos: 0 });
     },
-    unsubscribeAgencyPairStats(aid, gamePairId) {
-      const topic = agencyPairStatsTopic(aid, gamePairId);
+    unsubscribeAgencyPairStats(aid, pairId) {
+      const topic = agencyPairStatsTopic(aid, pairId);
       const entry = statsSubscriptions.get(topic);
       if (!entry) return;
       if (client) client.unsubscribe(entry.topic);
@@ -1355,22 +1360,25 @@ var RealtimeModule = class extends EventEmitter3 {
     this.#transport.unsubscribeWallet(cleanUserId);
   }
   /**
-   * Subscribe to public market candle data for a pair (e.g. "ETH/USD").
-   * Independent of game/agency — candle is market-wide public data.
+   * Subscribe to public market candle data for a pair, keyed by pairId
+   * (the #2 game_pairs.id, e.g. "grid-ETH-USD"). Independent of game/agency —
+   * candle is market-wide public data.
    */
-  subscribeCandle(pair, onCandle) {
-    this.#transport.subscribeCandle(pair, onCandle);
+  // REVIEW[bid-260602-v2]: param pairId (was: pair) — slash-free #2 game_pairs.id.
+  subscribeCandle(pairId, onCandle) {
+    this.#transport.subscribeCandle(pairId, onCandle);
   }
-  /** Unsubscribe from candle data for a pair. */
-  unsubscribeCandle(pair) {
-    this.#transport.unsubscribeCandle(pair);
+  /** Unsubscribe from candle data for a pairId. */
+  unsubscribeCandle(pairId) {
+    this.#transport.unsubscribeCandle(pairId);
   }
   /**
    * Subscribe to the live per-pair stats stream for the client's own agency.
    * Scoped to the agency the client was constructed with — there is no argument
    * to target another agency by design.
    */
-  subscribeAgencyPairStats(gamePairId, handler) {
+  // REVIEW[bid-260602-v2]: param pairId (was: gamePairId) — the #2 game_pairs.id.
+  subscribeAgencyPairStats(pairId, handler) {
     if (!this.#agencyId) {
       throw new TaphubError("agencyId is required to subscribe to agency pair stats", {
         code: "AgencyIdRequired"
@@ -1385,12 +1393,13 @@ var RealtimeModule = class extends EventEmitter3 {
         ts: Number(p.ts)
       });
     };
-    this.#transport.subscribeAgencyPairStats(this.#agencyId, gamePairId, onStats);
+    this.#transport.subscribeAgencyPairStats(this.#agencyId, pairId, onStats);
   }
   /** Unsubscribe from the per-pair stats stream for the client's own agency. */
-  unsubscribeAgencyPairStats(gamePairId) {
+  // REVIEW[bid-260602-v2]: param pairId (was: gamePairId).
+  unsubscribeAgencyPairStats(pairId) {
     if (!this.#agencyId) return;
-    this.#transport.unsubscribeAgencyPairStats(this.#agencyId, gamePairId);
+    this.#transport.unsubscribeAgencyPairStats(this.#agencyId, pairId);
   }
   disconnect() {
     for (const entry of this.#entries.values()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taphubhq/sdk-core",
-  "version": "0.16.2",
+  "version": "0.17.1",
   "description": "Core SDK for building on the TabHub platform",
   "license": "MIT",
   "main": "./dist/index.cjs",