pandora-cli-skills 1.1.4 → 1.1.6

package/README_FOR_SHARING.md

@@ -35,6 +35,13 @@ Prerequisite: Node.js `>=18`.
    - `ORACLE`
    - `FACTORY`
    - `USDC`
+   - optional for live mirror hedging:
+     - `POLYMARKET_PRIVATE_KEY`
+     - `POLYMARKET_FUNDER`
+     - `POLYMARKET_API_KEY`
+     - `POLYMARKET_API_SECRET`
+     - `POLYMARKET_API_PASSPHRASE`
+     - `POLYMARKET_HOST`
 4. Validate and build:
    - `npm run doctor`
    - `npm run build`
@@ -108,7 +115,7 @@ Prerequisite: Node.js `>=18`.
 - `pandora autopilot once --market-address <0x...> --side no --amount-usdc 10 --trigger-yes-below 15 --paper`
 - `pandora mirror plan --source polymarket --polymarket-market-id <id> --with-rules --include-similarity`
 - `pandora mirror verify --pandora-market-address <0x...> --polymarket-market-id <id> --include-similarity`
-- `pandora mirror sync once --pandora-market-address <0x...> --polymarket-market-id <id> --paper`
+- `pandora mirror sync once --pandora-market-address <0x...> --polymarket-market-id <id> --paper --hedge-ratio 1.0`
 - `pandora mirror status --strategy-hash <hash>`
 - `pandora webhook test --webhook-url https://example.com/hook`
 - `pandora leaderboard --metric volume --limit 20`
@@ -187,6 +194,8 @@ Prerequisite: Node.js `>=18`.
   - envelope is `ok=true`, `command="mirror.verify"`, with `data.matchConfidence`, `data.ruleHashLeft`, `data.ruleHashRight`, `data.ruleDiffSummary`, `data.similarityChecks[]`, and `data.gateResult`.
 - `mirror sync`:
   - envelope is `ok=true`, `command="mirror.sync"`, with `data.strategyHash`, `data.stateFile`, `data.parameters`, `data.snapshots[]`, and `data.actions[]`.
+  - hedge controls: `--hedge-trigger-usdc`, `--max-hedge-usdc`, `--hedge-ratio <n>` (default `1`), and `--no-hedge` to disable hedge execution while keeping drift rebalancing active.
+  - rebalance sizing is pool-aware: drift notional scales with `reserveYes + reserveNo`, then bounded by `--max-rebalance-usdc`.
 - `mirror status`:
   - envelope is `ok=true`, `command="mirror.status"`, with `data.stateFile`, `data.strategyHash`, and persisted `data.state`.
 - `webhook test`:

package/SKILL.md

@@ -100,7 +100,7 @@ pandora --output json arbitrage --venues pandora,polymarket --min-spread-pct 3 -
 pandora --output json autopilot once --market-address <0x...> --side no --amount-usdc 10 --trigger-yes-below 15 --paper
 pandora --output json mirror plan --source polymarket --polymarket-market-id <id> --with-rules --include-similarity
 pandora --output json mirror verify --pandora-market-address <0x...> --polymarket-market-id <id> --include-similarity
-pandora --output json mirror sync once --pandora-market-address <0x...> --polymarket-market-id <id> --paper
+pandora --output json mirror sync once --pandora-market-address <0x...> --polymarket-market-id <id> --paper --hedge-ratio 1.0
 pandora --output json mirror status --strategy-hash <hash>
 pandora --output json webhook test --webhook-url https://example.com/hook
 pandora --output json leaderboard --metric profit --limit 20
@@ -164,7 +164,9 @@ pandora --output json suggest --wallet <0x...> --risk medium --budget 50 --inclu
 - `mirror plan`: Polymarket mirror sizing plan with liquidity recommendation and distribution hint.
 - `mirror deploy`: dry-run/execute Pandora AMM deployment from mirror plan inputs.
 - `mirror verify`: explicit question/rules similarity endpoint for AI-subagent validation.
-- `mirror sync`: paper-first delta-neutral loop with strict gates, state persistence, and optional live hedging.
+- `mirror sync`: paper-first delta-neutral loop with strict gates, state persistence, and optional live hedging (`--hedge-ratio <n>`, `--no-hedge`).
+  - live hedge env: `POLYMARKET_PRIVATE_KEY`, `POLYMARKET_FUNDER`, `POLYMARKET_API_KEY`, `POLYMARKET_API_SECRET`, `POLYMARKET_API_PASSPHRASE`, `POLYMARKET_HOST`.
+  - rebalance sizing is pool-aware and bounded by `--max-rebalance-usdc`.
 - `mirror status`: local mirror state inspection (no network side effects).
 - `webhook test`: channel validation for generic, Telegram, and Discord payload delivery.
 - `leaderboard`: ranked user aggregates by profit/volume/win-rate.

package/cli/lib/mirror_sync_service.cjs

@@ -56,6 +56,7 @@ function evaluateSnapshot(verifyPayload, options) {
 
   const reserveYes = toNumber(pandora.reserveYes);
   const reserveNo = toNumber(pandora.reserveNo);
+  const reserveTotalUsdc = reserveYes !== null && reserveNo !== null ? round(reserveYes + reserveNo, 6) : null;
   const deltaLpUsdc = reserveYes !== null && reserveNo !== null ? round(reserveYes - reserveNo, 6) : null;
   const targetHedgeUsdc = deltaLpUsdc === null ? null : round(-deltaLpUsdc, 6);
 
@@ -64,6 +65,9 @@ function evaluateSnapshot(verifyPayload, options) {
     pandoraYesPct: pandoraYes,
     driftBps,
     driftTriggered,
+    reserveYesUsdc: reserveYes,
+    reserveNoUsdc: reserveNo,
+    reserveTotalUsdc,
     deltaLpUsdc,
     targetHedgeUsdc,
   };
@@ -152,6 +156,8 @@ async function runMirrorSync(options, deps = {}) {
     polymarketSlug: options.polymarketSlug,
     executeLive: options.executeLive,
     driftTriggerBps: options.driftTriggerBps,
+    hedgeEnabled: options.hedgeEnabled,
+    hedgeRatio: options.hedgeRatio,
     hedgeTriggerUsdc: options.hedgeTriggerUsdc,
   };
 
@@ -209,15 +215,20 @@ async function runMirrorSync(options, deps = {}) {
         snapshotMetrics.targetHedgeUsdc === null
           ? null
           : round(snapshotMetrics.targetHedgeUsdc - (toNumber(state.currentHedgeUsdc) || 0), 6);
-      const hedgeTriggered = gapUsdc !== null && Math.abs(gapUsdc) >= options.hedgeTriggerUsdc;
-
-      const plannedHedgeUsdc = hedgeTriggered
-        ? Math.min(Math.abs(gapUsdc), options.maxHedgeUsdc)
-        : 0;
-
-      const driftMagnitudePct = snapshotMetrics.driftBps === null ? 0 : snapshotMetrics.driftBps / 100;
+      const rawHedgeTriggered = gapUsdc !== null && Math.abs(gapUsdc) >= options.hedgeTriggerUsdc;
+      const hedgeTriggered = Boolean(options.hedgeEnabled) && rawHedgeTriggered;
+
+      const scaledHedgeUsdc = rawHedgeTriggered ? Math.abs(gapUsdc) * options.hedgeRatio : 0;
+      const plannedHedgeUsdc = hedgeTriggered ? Math.min(scaledHedgeUsdc, options.maxHedgeUsdc) : 0;
+
+      const driftFraction = snapshotMetrics.driftBps === null ? 0 : snapshotMetrics.driftBps / 10_000;
+      const rebalanceFromPoolUsdc =
+        snapshotMetrics.reserveTotalUsdc === null ? null : snapshotMetrics.reserveTotalUsdc * driftFraction;
+      const rebalanceFromDriftPointsUsdc = snapshotMetrics.driftBps === null ? 0 : snapshotMetrics.driftBps / 100;
+      const rebalanceSizingBasis = rebalanceFromPoolUsdc === null ? 'drift-points-fallback' : 'pool-size-drift';
+      const rebalanceCandidateUsdc = rebalanceFromPoolUsdc === null ? rebalanceFromDriftPointsUsdc : rebalanceFromPoolUsdc;
       const plannedRebalanceUsdc = snapshotMetrics.driftTriggered
-        ? Math.min(options.maxRebalanceUsdc, Math.max(1, driftMagnitudePct))
+        ? Math.min(options.maxRebalanceUsdc, Math.max(1, rebalanceCandidateUsdc))
         : 0;
 
       const plannedSpendUsdc = round(plannedHedgeUsdc + plannedRebalanceUsdc, 6) || 0;
@@ -249,8 +260,14 @@ async function runMirrorSync(options, deps = {}) {
         metrics: {
           ...snapshotMetrics,
           hedgeGapUsdc: gapUsdc,
+          rawHedgeTriggered,
           hedgeTriggered,
+          hedgeEnabled: Boolean(options.hedgeEnabled),
+          hedgeRatio: options.hedgeRatio,
+          hedgeSuppressed: rawHedgeTriggered && !options.hedgeEnabled,
           plannedHedgeUsdc,
+          rebalanceSizingBasis,
+          rebalanceCandidateUsdc: round(rebalanceCandidateUsdc, 6),
           plannedRebalanceUsdc,
           plannedSpendUsdc,
           depthWithinSlippageUsd: depth.depthWithinSlippageUsd,
@@ -314,7 +331,7 @@ async function runMirrorSync(options, deps = {}) {
           }
 
           if (hedgeTriggered && plannedHedgeUsdc > 0) {
-            const hedgeSide = gapUsdc >= 0 ? 'buy' : 'buy';
+            const hedgeSide = 'buy';
             const tokenId = gapUsdc >= 0 ? verifyPayload.sourceMarket.yesTokenId : verifyPayload.sourceMarket.noTokenId;
 
             if (options.executeLive) {
@@ -405,6 +422,8 @@ async function runMirrorSync(options, deps = {}) {
       intervalMs: options.intervalMs,
       driftTriggerBps: options.driftTriggerBps,
       hedgeTriggerUsdc: options.hedgeTriggerUsdc,
+      hedgeEnabled: options.hedgeEnabled,
+      hedgeRatio: options.hedgeRatio,
       maxRebalanceUsdc: options.maxRebalanceUsdc,
       maxHedgeUsdc: options.maxHedgeUsdc,
       maxOpenExposureUsdc: options.maxOpenExposureUsdc,

package/cli/pandora.cjs

@@ -245,7 +245,7 @@ Examples:
   pandora autopilot once --market-address 0xabc... --side no --amount-usdc 10 --trigger-yes-below 15 --paper
   pandora mirror plan --source polymarket --polymarket-market-id 0xabc... --with-rules --include-similarity
   pandora mirror verify --pandora-market-address 0xabc... --polymarket-market-id 0xdef... --include-similarity
-  pandora mirror sync once --pandora-market-address 0xabc... --polymarket-market-id 0xdef... --paper
+  pandora mirror sync once --pandora-market-address 0xabc... --polymarket-market-id 0xdef... --paper --hedge-ratio 1.0
   pandora webhook test --webhook-url https://example.com/hook --webhook-template '{\"text\":\"{{message}}\"}'
   pandora leaderboard --metric profit --limit 20
   pandora analyze --market-address 0xabc... --provider mock
@@ -2938,6 +2938,8 @@ function parseMirrorSyncFlags(args) {
     polymarketMarketId: null,
     polymarketSlug: null,
     executeLive: false,
+    hedgeEnabled: true,
+    hedgeRatio: 1,
     intervalMs: 5_000,
     driftTriggerBps: 150,
     hedgeTriggerUsdc: 10,
@@ -2995,6 +2997,10 @@ function parseMirrorSyncFlags(args) {
       options.executeLive = true;
       continue;
     }
+    if (token === '--no-hedge') {
+      options.hedgeEnabled = false;
+      continue;
+    }
     if (token === '--interval-ms') {
       options.intervalMs = parsePositiveInteger(requireFlagValue(rest, i, '--interval-ms'), '--interval-ms');
       if (options.intervalMs < 1_000) {
@@ -3013,6 +3019,14 @@ function parseMirrorSyncFlags(args) {
       i += 1;
       continue;
     }
+    if (token === '--hedge-ratio') {
+      options.hedgeRatio = parsePositiveNumber(requireFlagValue(rest, i, '--hedge-ratio'), '--hedge-ratio');
+      if (options.hedgeRatio > 2) {
+        throw new CliError('INVALID_FLAG_VALUE', '--hedge-ratio must be <= 2.');
+      }
+      i += 1;
+      continue;
+    }
     if (token === '--max-rebalance-usdc') {
       options.maxRebalanceUsdc = parsePositiveNumber(requireFlagValue(rest, i, '--max-rebalance-usdc'), '--max-rebalance-usdc');
       i += 1;
@@ -3140,6 +3154,8 @@ function parseMirrorSyncFlags(args) {
       polymarketSlug: options.polymarketSlug,
       executeLive: options.executeLive,
       driftTriggerBps: options.driftTriggerBps,
+      hedgeEnabled: options.hedgeEnabled,
+      hedgeRatio: options.hedgeRatio,
       hedgeTriggerUsdc: options.hedgeTriggerUsdc,
     });
   }
@@ -4175,6 +4191,8 @@ function renderAutopilotTable(data) {
     [
       ['mode', data.mode],
       ['executeLive', data.executeLive ? 'yes' : 'no'],
+      ['hedgeEnabled', data.parameters && data.parameters.hedgeEnabled === false ? 'no' : 'yes'],
+      ['hedgeRatio', data.parameters && data.parameters.hedgeRatio !== undefined ? data.parameters.hedgeRatio : ''],
       ['strategyHash', data.strategyHash],
       ['iterationsCompleted', data.iterationsCompleted],
       ['actionCount', data.actionCount],
@@ -6471,7 +6489,7 @@ async function runMirrorCommand(args, context) {
         '  verify --pandora-market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--include-similarity] [--with-rules]',
       );
       console.log(
-        '  sync run|once --pandora-market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--execute-live] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--state-file <path>] [--kill-switch-file <path>]',
+        '  sync run|once --pandora-market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--execute-live] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--state-file <path>] [--kill-switch-file <path>]',
       );
       console.log('  status --state-file <path>|--strategy-hash <hash>');
     }
@@ -6612,13 +6630,25 @@ async function runMirrorCommand(args, context) {
         emitSuccess(
           context.outputMode,
           'mirror.sync.help',
-          commandHelpPayload(
-            'pandora [--output table|json] mirror sync run|once --pandora-market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--execute-live] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--state-file <path>] [--kill-switch-file <path>]',
-          ),
+          {
+            usage:
+              'pandora [--output table|json] mirror sync run|once --pandora-market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--execute-live] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--state-file <path>] [--kill-switch-file <path>]',
+            liveHedgeEnv: [
+              'POLYMARKET_PRIVATE_KEY',
+              'POLYMARKET_FUNDER',
+              'POLYMARKET_API_KEY',
+              'POLYMARKET_API_SECRET',
+              'POLYMARKET_API_PASSPHRASE',
+              'POLYMARKET_HOST',
+            ],
+          },
         );
       } else {
         console.log(
-          'Usage: pandora [--output table|json] mirror sync run|once --pandora-market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--execute-live] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--state-file <path>] [--kill-switch-file <path>]',
+          'Usage: pandora [--output table|json] mirror sync run|once --pandora-market-address <address> --polymarket-market-id <id>|--polymarket-slug <slug> [--paper|--execute-live] [--interval-ms <ms>] [--drift-trigger-bps <n>] [--hedge-trigger-usdc <n>] [--hedge-ratio <n>] [--no-hedge] [--max-rebalance-usdc <n>] [--max-hedge-usdc <n>] [--max-open-exposure-usdc <n>] [--max-trades-per-day <n>] [--cooldown-ms <ms>] [--state-file <path>] [--kill-switch-file <path>]',
+        );
+        console.log(
+          'Live hedge env: POLYMARKET_PRIVATE_KEY, POLYMARKET_FUNDER, POLYMARKET_API_KEY, POLYMARKET_API_SECRET, POLYMARKET_API_PASSPHRASE, POLYMARKET_HOST.',
         );
       }
       return;

package/package.json

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

package/scripts/.env.example

@@ -5,3 +5,11 @@ PRIVATE_KEY=0x...
 ORACLE=0x259308E7d8557e4Ba192De1aB8Cf7e0E21896442
 FACTORY=0xaB120F1FD31FB1EC39893B75d80a3822b1Cd8d0c
 USDC=0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48
+
+# Optional: Polymarket live hedging credentials for `pandora mirror sync --execute-live`
+POLYMARKET_HOST=https://clob.polymarket.com
+POLYMARKET_PRIVATE_KEY=0x...
+POLYMARKET_FUNDER=
+POLYMARKET_API_KEY=
+POLYMARKET_API_SECRET=
+POLYMARKET_API_PASSPHRASE=