pandora-cli-skills 1.1.47 → 1.1.48

package/README.md

@@ -122,6 +122,7 @@ pandora --output json lifecycle resolve --id <lifecycle-id> --confirm
 - `pandora odds record|history`
 - `pandora autopilot run|once`
 - `pandora mirror browse|plan|deploy|verify|lp-explain|hedge-calc|simulate|go|sync|status|close`
+  - `mirror browse` supports `--polymarket-tag-id|--polymarket-tag-ids` (aliases `--sport-tag-id|--sport-tag-ids`) for sports-tagged Gamma event discovery.
 - `pandora polymarket check|approve|preflight|trade`
 - `pandora resolve`
 - `pandora lp add|remove|positions`

package/README_FOR_SHARING.md

@@ -200,6 +200,7 @@ Mirror advanced flags (for operator tuning):
 - `--sync-interval-ms <ms>` on `mirror go` to control auto-sync tick cadence.
 - `--oracle <address>` / `--factory <address>` on `mirror deploy` and `mirror go` for explicit contract overrides.
 - `--polymarket-gamma-mock-url <url>` on `mirror browse|plan|verify|go|sync|status` for deterministic mock-source testing.
+- `--polymarket-tag-id <id>` / `--polymarket-tag-ids <csv>` on `mirror browse` (aliases: `--sport-tag-id`, `--sport-tag-ids`) to query sports-tagged Gamma events.
 - `--no-stream` on `mirror sync` to disable per-tick stdout line streaming in run mode.
 - `--pid-file <path>` on `mirror sync stop|status` for explicit daemon process selection.
 
@@ -219,7 +220,7 @@ Mirror advanced flags (for operator tuning):
 - `pandora export --wallet <0x...> --format csv --out ./trades.csv`
 - `pandora arbitrage --venues pandora,polymarket --min-spread-pct 2 --cross-venue-only --with-rules --include-similarity`
 - `pandora autopilot once --market-address <0x...> --side no --amount-usdc 10 --trigger-yes-below 15 --paper`
-- `pandora mirror browse --min-yes-pct 20 --max-yes-pct 80 --min-volume-24h 100000 --limit 10`
+- `pandora mirror browse --polymarket-tag-id 82 --min-yes-pct 20 --max-yes-pct 80 --min-volume-24h 100000 --limit 10`
 - `pandora mirror plan --source polymarket --polymarket-market-id <id> --with-rules --include-similarity`
 - `pandora mirror go --polymarket-slug <slug> --liquidity-usdc 10 --paper`
 - `pandora mirror verify --pandora-market-address <0x...> --polymarket-market-id <id> --include-similarity`

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: pandora-cli-skills
 summary: Canonical skill and operator guide for Pandora CLI including mirror, polymarket, resolve, and LP flows.
-version: 1.1.46
+version: 1.1.48
 ---
 
 # Pandora CLI & Skills
@@ -317,7 +317,7 @@ pandora --output json history --wallet <0x...> --limit 50
 pandora --output json export --wallet <0x...> --format csv --out ./trades.csv
 pandora --output json arbitrage --venues pandora,polymarket --min-spread-pct 3 --cross-venue-only --with-rules --include-similarity
 pandora --output json autopilot once --market-address <0x...> --side no --amount-usdc 10 --trigger-yes-below 15 --paper
-pandora --output json mirror browse --min-yes-pct 20 --max-yes-pct 80 --min-volume-24h 100000 --limit 10
+pandora --output json mirror browse --polymarket-tag-id 82 --min-yes-pct 20 --max-yes-pct 80 --min-volume-24h 100000 --limit 10
 pandora --output json mirror plan --source polymarket --polymarket-market-id <id> --with-rules --include-similarity
 pandora --output json mirror lp-explain --liquidity-usdc 10000 --source-yes-pct 58
 pandora --output json mirror hedge-calc --reserve-yes-usdc 8 --reserve-no-usdc 12 --excess-no-usdc 2 --polymarket-yes-pct 60
@@ -562,7 +562,8 @@ Error envelope:
   - `{ ok: true, command: "autopilot", data: { schemaVersion, generatedAt, strategyHash, mode, executeLive, stateFile, killSwitchFile, iterationsRequested, iterationsCompleted, stoppedReason?, parameters: { marketAddress, side, amountUsdc, triggerYesBelow?, triggerYesAbove?, intervalMs, cooldownMs, maxAmountUsdc?, maxOpenExposureUsdc, dailySpendCapUsdc, maxTradesPerDay }, state, actionCount, actions[], snapshots[], webhookReports[] } }`
 - `mirror browse`:
   - `{ ok: true, command: "mirror.browse", data: { schemaVersion, generatedAt, source, gammaApiError, filters, count, items[], diagnostics[] } }`
-  - each candidate row can include `existingMirror: { marketAddress, similarity } | null`.
+  - `filters` can include `polymarketTagIds[]` when using `--polymarket-tag-id|--polymarket-tag-ids` (or `--sport-tag-id|--sport-tag-ids` aliases).
+  - each candidate row can include `eventId`, `eventSlug`, `eventTitle`, and `existingMirror: { marketAddress, similarity } | null`.
 - `mirror go`:
   - `{ ok: true, command: "mirror.go", data: { schemaVersion, generatedAt, mode, plan, deploy, verify, sync, polymarketPreflight, suggestedSyncCommand, trustManifest, diagnostics[] } }`
   - `plan` is the same payload shape as `mirror.plan`; `deploy` is the same payload shape as `mirror.deploy`; `sync` is null unless `--auto-sync` is used.

package/cli/lib/mirror_command_service.cjs

@@ -91,7 +91,7 @@ function createRunMirrorCommand(deps) {
         console.log('');
         console.log('Subcommands:');
         console.log(
-          '  browse --min-yes-pct <n> --max-yes-pct <n> --min-volume-24h <n> [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--chain-id <id>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]',
+          '  browse --min-yes-pct <n> --max-yes-pct <n> --min-volume-24h <n> [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--chain-id <id>] [--polymarket-tag-id <id>] [--polymarket-tag-ids <csv>] [--sport-tag-id <id>] [--sport-tag-ids <csv>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]',
         );
         console.log(
           '  plan   --source polymarket --polymarket-market-id <id>|--polymarket-slug <slug> [--chain-id <id>] [--target-slippage-bps <n>] [--turnover-target <n>] [--depth-slippage-bps <n>] [--safety-multiplier <n>] [--min-liquidity-usdc <n>] [--max-liquidity-usdc <n>] [--with-rules] [--include-similarity] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]',

package/cli/lib/mirror_handlers/browse.cjs

@@ -22,12 +22,12 @@ module.exports = async function handleMirrorBrowse({ shared, context, deps }) {
         context.outputMode,
         'mirror.browse.help',
         commandHelpPayload(
-          'pandora [--output table|json] mirror browse [--min-yes-pct <n>] [--max-yes-pct <n>] [--min-volume-24h <n>] [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>]',
+          'pandora [--output table|json] mirror browse [--min-yes-pct <n>] [--max-yes-pct <n>] [--min-volume-24h <n>] [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--polymarket-tag-id <id>] [--polymarket-tag-ids <csv>] [--sport-tag-id <id>] [--sport-tag-ids <csv>]',
         ),
       );
     } else {
       console.log(
-        'Usage: pandora [--output table|json] mirror browse [--min-yes-pct <n>] [--max-yes-pct <n>] [--min-volume-24h <n>] [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>]',
+        'Usage: pandora [--output table|json] mirror browse [--min-yes-pct <n>] [--max-yes-pct <n>] [--min-volume-24h <n>] [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--polymarket-tag-id <id>] [--polymarket-tag-ids <csv>] [--sport-tag-id <id>] [--sport-tag-ids <csv>]',
       );
     }
     return;

package/cli/lib/mirror_service.cjs

@@ -395,6 +395,7 @@ async function browseMirrorMarkets(options = {}) {
     gammaUrl: options.polymarketGammaUrl,
     gammaMockUrl: options.polymarketGammaMockUrl,
     mockUrl: options.polymarketMockUrl,
+    polymarketTagIds: Array.isArray(options.polymarketTagIds) ? options.polymarketTagIds : [],
     timeoutMs: options.timeoutMs,
     minYesPct: options.minYesPct,
     maxYesPct: options.maxYesPct,

package/cli/lib/parsers/mirror_remaining_flags.cjs

@@ -39,8 +39,13 @@ function createParseMirrorBrowseFlags(deps) {
       polymarketGammaUrl: null,
       polymarketGammaMockUrl: null,
       polymarketMockUrl: null,
+      polymarketTagIds: [],
     };
 
+    function pushTagId(rawValue, flagName) {
+      options.polymarketTagIds.push(parsePositiveInteger(rawValue, flagName));
+    }
+
     for (let i = 0; i < args.length; i += 1) {
       const token = args[i];
       if (token === '--min-yes-pct') {
@@ -98,6 +103,26 @@ function createParseMirrorBrowseFlags(deps) {
         i += 1;
         continue;
       }
+      if (token === '--polymarket-tag-id' || token === '--sport-tag-id') {
+        pushTagId(requireFlagValue(args, i, token), token);
+        i += 1;
+        continue;
+      }
+      if (token === '--polymarket-tag-ids' || token === '--sport-tag-ids') {
+        const raw = requireFlagValue(args, i, token);
+        const values = String(raw)
+          .split(',')
+          .map((value) => value.trim())
+          .filter(Boolean);
+        if (!values.length) {
+          throw new CliError('INVALID_FLAG_VALUE', `${token} must include at least one positive integer tag id.`);
+        }
+        for (const value of values) {
+          pushTagId(value, token);
+        }
+        i += 1;
+        continue;
+      }
       throw new CliError('UNKNOWN_FLAG', `Unknown flag for mirror browse: ${token}`);
     }
 
@@ -105,6 +130,10 @@ function createParseMirrorBrowseFlags(deps) {
       throw new CliError('INVALID_ARGS', '--min-yes-pct cannot be greater than --max-yes-pct.');
     }
 
+    if (options.polymarketTagIds.length) {
+      options.polymarketTagIds = Array.from(new Set(options.polymarketTagIds));
+    }
+
     return options;
   };
 }

package/cli/lib/polymarket_trade_adapter.cjs

@@ -405,6 +405,9 @@ function normalizeMarketRow(row) {
     ).trim() || null,
     slug: String((row && (row.market_slug || row.marketSlug || row.slug)) || '').trim() || null,
     question: extractQuestionText(row),
+    eventId: toStringOrNull(row && (row.event_id || row.eventId)),
+    eventSlug: toStringOrNull(row && (row.event_slug || row.eventSlug)),
+    eventTitle: toStringOrNull(row && (row.event_title || row.eventTitle)),
     description: rulesSections.length ? rulesSections.join('\n\n') : null,
     closeTimestamp: toTimestampSeconds(
       row &&
@@ -479,6 +482,14 @@ function parseMarketsPayload(payload) {
   return [];
 }
 
+function parseEventsPayload(payload) {
+  if (Array.isArray(payload)) return payload;
+  if (payload && Array.isArray(payload.events)) return payload.events;
+  if (payload && payload.data && Array.isArray(payload.data.events)) return payload.data.events;
+  if (payload && Array.isArray(payload.data)) return payload.data;
+  return [];
+}
+
 async function fetchJson(url, timeoutMs) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), timeoutMs);
@@ -530,6 +541,15 @@ function buildGammaUrl(baseUrl, params) {
   return url.toString();
 }
 
+function buildGammaEventsUrl(baseUrl, params) {
+  const url = new URL(`${baseUrl}/events`);
+  for (const [key, value] of Object.entries(params || {})) {
+    if (value === null || value === undefined || value === '') continue;
+    url.searchParams.set(key, String(value));
+  }
+  return url.toString();
+}
+
 async function fetchGammaRows(params, options = {}, diagnostics = []) {
   const timeoutMs = Number.isInteger(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 12_000;
   const gammaUrl = normalizeGammaBaseUrl(options.gammaUrl);
@@ -543,6 +563,120 @@ async function fetchGammaRows(params, options = {}, diagnostics = []) {
   }
 }
 
+function makeMarketDedupeKey(row) {
+  return (
+    normalizeText(
+      row &&
+        (row.condition_id ||
+          row.conditionId ||
+          row.question_id ||
+          row.questionId ||
+          row.market_id ||
+          row.marketId ||
+          row.id ||
+          row.slug),
+    ) || null
+  );
+}
+
+function flattenEventMarkets(events) {
+  const output = [];
+  const seen = new Set();
+
+  for (const event of Array.isArray(events) ? events : []) {
+    const markets = Array.isArray(event && event.markets) ? event.markets : [];
+    for (const market of markets) {
+      if (!market || typeof market !== 'object') continue;
+      const dedupeKey = makeMarketDedupeKey(market);
+      if (dedupeKey && seen.has(dedupeKey)) continue;
+      if (dedupeKey) seen.add(dedupeKey);
+      output.push({
+        ...market,
+        event_id: event && event.id !== undefined ? event.id : null,
+        event_slug: event && event.slug ? event.slug : null,
+        event_title: event && event.title ? event.title : null,
+        event_tags: Array.isArray(event && event.tags) ? event.tags : [],
+      });
+    }
+  }
+
+  return output;
+}
+
+function normalizeTagIdList(input) {
+  const values = Array.isArray(input) ? input : [];
+  const normalized = [];
+  for (const value of values) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric)) continue;
+    const asInt = Math.trunc(numeric);
+    if (asInt <= 0) continue;
+    normalized.push(asInt);
+  }
+  return Array.from(new Set(normalized));
+}
+
+async function fetchGammaRowsByTagIds(params, options = {}, diagnostics = []) {
+  const timeoutMs = Number.isInteger(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 12_000;
+  const gammaUrl = normalizeGammaBaseUrl(options.gammaUrl);
+  const tagIds = normalizeTagIdList(params && params.tagIds);
+  if (!tagIds.length) return [];
+
+  if (options.gammaMockUrl) {
+    try {
+      const payload = await fetchJson(options.gammaMockUrl, timeoutMs);
+      const events = parseEventsPayload(payload);
+      return flattenEventMarkets(events);
+    } catch (err) {
+      diagnostics.push(`Gamma sports-events request failed (${options.gammaMockUrl}): ${formatNetworkError(err)}`);
+      return [];
+    }
+  }
+
+  const allRows = [];
+  const perTagResults = await Promise.all(
+    tagIds.map(async (tagId) => {
+      const queryParams = {
+        ...(params || {}),
+        tag_id: tagId,
+      };
+      delete queryParams.tagIds;
+      const targetUrl = buildGammaEventsUrl(gammaUrl, queryParams);
+      try {
+        const payload = await fetchJson(targetUrl, timeoutMs);
+        const events = parseEventsPayload(payload);
+        return {
+          rows: flattenEventMarkets(events),
+          error: null,
+        };
+      } catch (err) {
+        return {
+          rows: [],
+          error: `Gamma sports-events request failed (${targetUrl}): ${formatNetworkError(err)}`,
+        };
+      }
+    }),
+  );
+
+  for (const result of perTagResults) {
+    if (result.error) {
+      diagnostics.push(result.error);
+      continue;
+    }
+    allRows.push(...result.rows);
+  }
+
+  const deduped = [];
+  const seen = new Set();
+  for (const row of allRows) {
+    const dedupeKey = makeMarketDedupeKey(row);
+    if (dedupeKey && seen.has(dedupeKey)) continue;
+    if (dedupeKey) seen.add(dedupeKey);
+    deduped.push(row);
+  }
+  return deduped;
+}
+
 function extractConditionId(row) {
   const value = toStringOrNull(
     row &&
@@ -998,21 +1132,38 @@ async function browsePolymarketMarkets(options = {}) {
   const timeoutMs = Number.isInteger(options.timeoutMs) && options.timeoutMs > 0 ? options.timeoutMs : 12_000;
   const requestedLimit = Number.isInteger(Number(options.limit)) && Number(options.limit) > 0 ? Number(options.limit) : 10;
   const scanLimit = Math.max(requestedLimit * 5, 100);
+  const polymarketTagIds = normalizeTagIdList(options.polymarketTagIds);
+  const useSportsEventsEndpoint = polymarketTagIds.length > 0;
 
   let rows = [];
+  let sourceType = options.mockUrl ? 'polymarket:mock' : 'polymarket:gamma';
   if (options.mockUrl) {
     const payload = await fetchMockPayload(options.mockUrl, timeoutMs);
     rows = parseMarketsPayload(payload);
   } else {
-    rows = await fetchGammaRows(
-      {
-        active: true,
-        closed: false,
-        limit: Math.min(scanLimit, 500),
-      },
-      options,
-      diagnostics,
-    );
+    if (useSportsEventsEndpoint) {
+      rows = await fetchGammaRowsByTagIds(
+        {
+          tagIds: polymarketTagIds,
+          active: true,
+          closed: false,
+          limit: Math.min(scanLimit, 500),
+        },
+        options,
+        diagnostics,
+      );
+      sourceType = 'polymarket:gamma-events';
+    } else {
+      rows = await fetchGammaRows(
+        {
+          active: true,
+          closed: false,
+          limit: Math.min(scanLimit, 500),
+        },
+        options,
+        diagnostics,
+      );
+    }
   }
 
   const minYesPct = toOptionalNumber(options.minYesPct);
@@ -1039,6 +1190,9 @@ async function browsePolymarketMarkets(options = {}) {
   const items = filtered.slice(0, requestedLimit).map((item) => ({
     marketId: item.marketId,
     slug: item.slug,
+    eventId: item.eventId,
+    eventSlug: item.eventSlug,
+    eventTitle: item.eventTitle,
     question: item.question,
     closeTimestamp: item.closeTimestamp,
     yesPct: item.yesPct,
@@ -1048,16 +1202,16 @@ async function browsePolymarketMarkets(options = {}) {
     active: item.active,
     resolved: item.resolved,
     url: item.url,
-    sourceType: item.source || (options.mockUrl ? 'polymarket:mock' : 'polymarket:gamma'),
+    sourceType: item.source || sourceType,
   }));
 
   const gammaApiError =
-    diagnostics.find((line) => /^Gamma request failed/i.test(String(line || ''))) || null;
+    diagnostics.find((line) => /^Gamma( sports-events)? request failed/i.test(String(line || ''))) || null;
 
   return {
     schemaVersion: '1.0.0',
     generatedAt: new Date().toISOString(),
-    source: options.mockUrl ? 'polymarket:mock' : 'polymarket:gamma',
+    source: sourceType,
     filters: {
       minYesPct,
       maxYesPct,
@@ -1066,6 +1220,7 @@ async function browsePolymarketMarkets(options = {}) {
       closesBefore,
       questionContains: options.questionContains || null,
       limit: requestedLimit,
+      polymarketTagIds,
     },
     count: items.length,
     items,

package/cli/lib/schema_command_service.cjs

@@ -264,6 +264,13 @@ function buildCommandDescriptors() {
       emits: ['sports.resolve.plan', 'sports.help'],
       dataSchema: '#/definitions/SportsResolvePlanPayload',
     }),
+    'mirror.browse': commandDescriptor({
+      summary: 'Browse Polymarket mirror candidates with optional sports tag filters.',
+      usage:
+        'pandora [--output table|json] mirror browse [--min-yes-pct <n>] [--max-yes-pct <n>] [--min-volume-24h <n>] [--closes-after <date>] [--closes-before <date>] [--question-contains <text>] [--limit <n>] [--chain-id <id>] [--polymarket-tag-id <id>] [--polymarket-tag-ids <csv>] [--sport-tag-id <id>] [--sport-tag-ids <csv>] [--polymarket-gamma-url <url>] [--polymarket-gamma-mock-url <url>] [--polymarket-mock-url <url>]',
+      emits: ['mirror.browse', 'mirror.browse.help'],
+      dataSchema: '#/definitions/MirrorBrowsePayload',
+    }),
     'mirror.plan': commandDescriptor({
       summary: 'Generate mirror sizing/distribution plan from Polymarket source.',
       usage:
@@ -812,6 +819,19 @@ function buildSchemaPayload() {
           generatedAt: { type: 'string', format: 'date-time' },
         },
       },
+      MirrorBrowsePayload: {
+        type: 'object',
+        properties: {
+          source: { type: 'string' },
+          gammaApiError: { type: ['string', 'null'] },
+          filters: { type: 'object' },
+          count: { type: 'integer' },
+          items: { type: 'array', items: { type: 'object' } },
+          diagnostics: { type: 'array', items: { type: 'string' } },
+          schemaVersion: { type: 'string' },
+          generatedAt: { type: 'string', format: 'date-time' },
+        },
+      },
       MirrorPlanPayload: {
         type: 'object',
         properties: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pandora-cli-skills",
-  "version": "1.1.47",
+  "version": "1.1.48",
   "description": "Pandora CLI & Skills",
   "main": "cli/pandora.cjs",
   "bin": {

package/tests/cli/cli.integration.test.cjs

@@ -1090,6 +1090,9 @@ test('schema command returns envelope schema plus command descriptors', () => {
   assert.ok(payload.data.commandDescriptors.quote.emits.includes('quote'));
   assert.ok(payload.data.commandDescriptors.trade);
   assert.equal(payload.data.commandDescriptors.trade.dataSchema, '#/definitions/TradePayload');
+  assert.ok(payload.data.commandDescriptors['mirror.browse']);
+  assert.equal(payload.data.commandDescriptors['mirror.browse'].dataSchema, '#/definitions/MirrorBrowsePayload');
+  assert.match(payload.data.commandDescriptors['mirror.browse'].usage, /--polymarket-tag-id/);
   assert.ok(payload.data.commandDescriptors['mirror.plan']);
   assert.equal(payload.data.commandDescriptors['mirror.plan'].dataSchema, '#/definitions/MirrorPlanPayload');
   assert.ok(payload.data.commandDescriptors['risk.show']);
@@ -1150,6 +1153,7 @@ test('schema command returns envelope schema plus command descriptors', () => {
   assert.ok(payload.data.definitions.ModelCorrelationPayload);
   assert.ok(payload.data.definitions.ModelDiagnosePayload);
   assert.ok(payload.data.definitions.ErrorRecoveryPayload);
+  assert.ok(payload.data.definitions.MirrorBrowsePayload);
 });
 
 test('schema command rejects unknown trailing flags', () => {
@@ -4825,6 +4829,24 @@ test('mirror browse rejects invalid calendar rollover dates', () => {
   assert.match(payload.error.message, /real calendar date/);
 });
 
+test('mirror browse rejects invalid tag id values', () => {
+  const result = runCli(['--output', 'json', 'mirror', 'browse', '--polymarket-tag-id', '0']);
+  assert.equal(result.status, 1);
+  const payload = parseJsonOutput(result);
+  assert.equal(payload.ok, false);
+  assert.equal(payload.error.code, 'INVALID_FLAG_VALUE');
+  assert.match(payload.error.message, /--polymarket-tag-id must be a positive integer/i);
+});
+
+test('mirror browse rejects empty tag-id csv values', () => {
+  const result = runCli(['--output', 'json', 'mirror', 'browse', '--polymarket-tag-ids', ', ,']);
+  assert.equal(result.status, 1);
+  const payload = parseJsonOutput(result);
+  assert.equal(payload.ok, false);
+  assert.equal(payload.error.code, 'INVALID_FLAG_VALUE');
+  assert.match(payload.error.message, /must include at least one positive integer tag id/i);
+});
+
 test('boolean flags with --key=false do not silently flip behavior', () => {
   const result = runCli(['--output', 'json', 'scan', '--active=false']);
   assert.equal(result.status, 1);
@@ -4924,6 +4946,83 @@ test('mirror browse returns candidate markets with existing mirror hint', async
   }
 });
 
+test('mirror browse supports sports tag filters via gamma events endpoint', async () => {
+  const gamma = await startJsonHttpServer((request) => {
+    const parsed = new URL(request.url || '/', 'http://127.0.0.1');
+    if (parsed.pathname !== '/events') {
+      return { status: 404, body: { error: 'not found' } };
+    }
+
+    const tagId = parsed.searchParams.get('tag_id');
+    if (tagId !== '82') {
+      return { body: { events: [] } };
+    }
+
+    return {
+      body: {
+        events: [
+          {
+            id: 'evt-epl-1',
+            slug: 'everton-v-burnley',
+            title: 'Everton vs Burnley',
+            markets: [
+              {
+                condition_id: 'poly-epl-c1',
+                market_slug: 'everton-v-burnley-home',
+                question: 'Will Everton beat Burnley?',
+                end_date_iso: FIXED_MIRROR_CLOSE_ISO,
+                active: true,
+                closed: false,
+                volume24hr: 550000,
+                tokens: [
+                  { outcome: 'Yes', price: '0.605', token_id: 'poly-epl-yes-1' },
+                  { outcome: 'No', price: '0.395', token_id: 'poly-epl-no-1' },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    };
+  });
+
+  try {
+    const result = await runCliAsync([
+      '--output',
+      'json',
+      'mirror',
+      'browse',
+      '--skip-dotenv',
+      '--polymarket-gamma-url',
+      gamma.url,
+      '--polymarket-tag-id',
+      '82',
+      '--limit',
+      '5',
+    ]);
+
+    assert.equal(result.status, 0);
+    const payload = parseJsonOutput(result);
+    assert.equal(payload.ok, true);
+    assert.equal(payload.command, 'mirror.browse');
+    assert.equal(payload.data.source, 'polymarket:gamma-events');
+    assert.deepEqual(payload.data.filters.polymarketTagIds, [82]);
+    assert.equal(payload.data.count, 1);
+    assert.equal(payload.data.items[0].eventSlug, 'everton-v-burnley');
+    assert.equal(payload.data.items[0].eventTitle, 'Everton vs Burnley');
+    assert.equal(payload.data.items[0].eventId, 'evt-epl-1');
+
+    const eventRequest = gamma.requests.find((entry) => String(entry.url || '').startsWith('/events?'));
+    assert.ok(eventRequest);
+    const parsed = new URL(eventRequest.url, 'http://127.0.0.1');
+    assert.equal(parsed.searchParams.get('tag_id'), '82');
+    assert.equal(parsed.searchParams.get('active'), 'true');
+    assert.equal(parsed.searchParams.get('closed'), 'false');
+  } finally {
+    await gamma.close();
+  }
+});
+
 test('mirror sync accepts --market-address with --dry-run mode alias', async () => {
   const tempDir = createTempDir('pandora-mirror-sync-aliases-');
   const stateFile = path.join(tempDir, 'mirror-state.json');

package/tests/unit/new-features.test.cjs

@@ -1027,6 +1027,124 @@ test('browsePolymarketMarkets filters mock payload deterministically', async ()
   }
 });
 
+test('browsePolymarketMarkets uses gamma events endpoint for tag-id sports discovery', async () => {
+  const requests = [];
+  const server = http.createServer((req, res) => {
+    requests.push(req.url || '/');
+    const parsed = new URL(req.url || '/', 'http://127.0.0.1');
+    const tagId = parsed.searchParams.get('tag_id');
+
+    res.statusCode = 200;
+    res.setHeader('content-type', 'application/json');
+
+    if (parsed.pathname !== '/events') {
+      res.end(JSON.stringify({ events: [] }));
+      return;
+    }
+
+    if (tagId === '82') {
+      res.end(
+        JSON.stringify({
+          events: [
+            {
+              id: 'evt-82',
+              slug: 'everton-v-burnley',
+              title: 'Everton vs Burnley',
+              markets: [
+                {
+                  condition_id: 'sports-c1',
+                  market_slug: 'everton-v-burnley-home',
+                  question: 'Will Everton beat Burnley?',
+                  end_date_iso: '2030-03-09T16:00:00Z',
+                  active: true,
+                  closed: false,
+                  volume24hr: 500000,
+                  tokens: [
+                    { outcome: 'Yes', price: '0.605', token_id: 'yes-sports-1' },
+                    { outcome: 'No', price: '0.395', token_id: 'no-sports-1' },
+                  ],
+                },
+              ],
+            },
+          ],
+        }),
+      );
+      return;
+    }
+
+    if (tagId === '100350') {
+      res.end(
+        JSON.stringify({
+          events: [
+            {
+              id: 'evt-100350',
+              slug: 'leeds-v-sunderland',
+              title: 'Leeds vs Sunderland',
+              markets: [
+                {
+                  // Duplicate condition id should be deduped across tag-id scans.
+                  condition_id: 'sports-c1',
+                  market_slug: 'duplicate-market-ignored',
+                  question: 'Duplicate row should be ignored',
+                  end_date_iso: '2030-03-09T16:00:00Z',
+                  active: true,
+                  closed: false,
+                  volume24hr: 1,
+                  tokens: [
+                    { outcome: 'Yes', price: '0.5', token_id: 'dup-yes' },
+                    { outcome: 'No', price: '0.5', token_id: 'dup-no' },
+                  ],
+                },
+                {
+                  condition_id: 'sports-c2',
+                  market_slug: 'leeds-v-sunderland-home',
+                  question: 'Will Leeds beat Sunderland?',
+                  end_date_iso: '2030-03-09T16:00:00Z',
+                  active: true,
+                  closed: false,
+                  volume24hr: 400000,
+                  tokens: [
+                    { outcome: 'Yes', price: '0.495', token_id: 'yes-sports-2' },
+                    { outcome: 'No', price: '0.505', token_id: 'no-sports-2' },
+                  ],
+                },
+              ],
+            },
+          ],
+        }),
+      );
+      return;
+    }
+
+    res.end(JSON.stringify({ events: [] }));
+  });
+
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  const { port } = server.address();
+  const gammaUrl = `http://127.0.0.1:${port}`;
+
+  try {
+    const payload = await browsePolymarketMarkets({
+      gammaUrl,
+      polymarketTagIds: [82, 100350],
+      limit: 10,
+    });
+
+    assert.equal(payload.source, 'polymarket:gamma-events');
+    assert.deepEqual(payload.filters.polymarketTagIds, [82, 100350]);
+    assert.equal(payload.count, 2);
+    assert.equal(payload.items[0].eventSlug, 'everton-v-burnley');
+    assert.equal(payload.items[1].eventSlug, 'leeds-v-sunderland');
+    assert.equal(payload.items[0].eventTitle, 'Everton vs Burnley');
+    assert.equal(payload.items[0].eventId, 'evt-82');
+
+    const eventRequests = requests.filter((entry) => String(entry).startsWith('/events?'));
+    assert.equal(eventRequests.length, 2);
+  } finally {
+    await new Promise((resolve) => server.close(resolve));
+  }
+});
+
 test('computeApprovalDiff deterministically marks missing allowance/operator checks', () => {
   const payload = computeApprovalDiff({
     ownerAddress: '0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa',