jingswap-cycle-agent

# jingswap-cycle-agent ## What it does Monitors the active JingSwap cycle and evaluates whether the Pyth oracle settlement rate offers a favourable sBTC acquisition opportunity relative to live DEX prices. | Data source | What it reads | Why it matters | |---|---|---| | `sbtc-stx-jing-v2` contract (Hiro read-only API) | Cycle ID, phase, blocks elapsed, deposits, minimums | Is the cycle in deposit phase? Is sBTC available? | | Pyth Hermes oracle | BTC/USD and STX/USD live prices | Computes oracle STX/sBTC settlement rate | | `get-dlmm-price` (contract) | DLMM pool price (1e10 / raw) | Best DEX rate for comparison | | `get-xyk-price` (contract) | XYK pool price (raw / 1e8) | Secondary DEX rate cross-check | JingSwap settles at the Pyth oracle rate, not the DEX rate. When oracle < DEX, depositing STX acquires sBTC cheaper than buying on-market — the arbitrage window. This skill quantifies that spread in real time. ## Why agents need it JingSwap's API (`faktory-dao-backend.vercel.app`) requires an `x-api-key`. This skill bypasses it entirely by reading the Stacks contract directly via the public Hiro read-only endpoint. No credentials needed. The `analyze` command distils the cycle state + two price sources into a single `action` field — agents don't need to know the contract encoding or Pyth feed IDs. ## Safety notes - Read-only for `doctor`, `status`, `analyze` — no wallet required. - `participate` (without `--dry-run`) outputs a `DEPOSIT_READY` JSON payload — **parent agent must confirm** before calling `jingswap_deposit_stx`. - Mainnet only — JingSwap v2 contract is mainnet-only. - Always uses live contract reads — never caches cycle state. ## Commands ### doctor Checks Hiro contract API and Pyth Hermes connectivity. ```bash bun run jingswap-cycle-agent/jingswap-cycle-agent.ts doctor ``` Output: ```json { "result": "ready", "checks": { "hiro_contract_api": "ok", "pyth_hermes_api": "ok" }, "contract": "SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-stx-jing-v2" } ``` ### status Fetches full cycle state + price snapshot. ```bash bun run jingswap-cycle-agent/jingswap-cycle-agent.ts status ``` Output: ```json { "skill": "jingswap-cycle-agent", "timestamp": "2026-03-29T15:22:18.792Z", "contract": "SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-stx-jing-v2", "cycle": { "id": 9, "phase": "deposit", "blocks_elapsed": 191, "sbtc_deposited": "0.01929494 sBTC", "stx_deposited": "0.00 STX", "min_stx_deposit": "1.00 STX", "min_sbtc_deposit": "0.00001000 sBTC" }, "prices": { "btc_usd": "66488.42", "stx_usd": "0.216440", "oracle_stx_per_sbtc": "307191.64", "dex_stx_per_sbtc_dlmm": "305922.66", "dex_stx_per_sbtc_xyk": "305306.01", "oracle_vs_dex_discount_pct": "-0.394" }, "summary": "Cycle 9 in deposit phase. Oracle 0.39% MORE EXPENSIVE than DEX." } ``` ### analyze Evaluates whether the current cycle offers a favourable entry. ```bash bun run jingswap-cycle-agent/jingswap-cycle-agent.ts analyze bun run jingswap-cycle-agent/jingswap-cycle-agent.ts analyze --min-discount 2.0 ``` Options: - `--min-discount <pct>` (default: `1.0`) — minimum oracle discount vs DEX to trigger PARTICIPATE Output: ```json { "skill": "jingswap-cycle-agent", "timestamp": "2026-03-29T15:22:27.573Z", "contract": "SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-stx-jing-v2", "input": { "min_discount_pct": 1 }, "cycle": { "id": 9, "phase": "deposit", "sbtc_available": "0.01929494 sBTC", "stx_deposited": "0.00 STX" }, "pricing": { "oracle_stx_per_sbtc": "307148.46", "dex_stx_per_sbtc": "305922.66", "discount_pct": "-0.401" }, "action": "MONITOR", "confidence": "high", "is_favourable": false, "rationale": "Oracle rate (307148 STX/sBTC) is 0.40% MORE expensive than DEX (305923 STX/sBTC). Spread does not meet minimum discount threshold of 1%.", "summary": "MONITOR (high confidence) — cycle 9 (deposit), oracle 0.40% premium vs DEX." } ``` ### participate Evaluates opportunity and (if favourable) prepares deposit parameters for parent agent execution. ```bash bun run jingswap-cycle-agent/jingswap-cycle-agent.ts participate --amount-stx 100 bun run jingswap-cycle-agent/jingswap-cycle-agent.ts participate --amount-stx 100 --min-discount 2.0 --dry-run ``` Options: - `--amount-stx <amount>` (required) — STX amount to deposit - `--min-discount <pct>` (default: `1.0`) — minimum discount required to proceed - `--dry-run` — analyse only, do not output execution payload When favourable, outputs: ```json { "skill": "jingswap-cycle-agent", "action": "DEPOSIT_READY", "deposit_params": { "amount_stx": 100, "amount_micro_stx": 100000000, "market": "sbtc-stx", "cycle": 9 }, "instruction": "Parent agent: call jingswap_deposit_stx with amount=100000000 and market=sbtc-stx to execute this deposit. Confirm before proceeding." } ``` ## Action values | Action | Meaning | |---|---| | `PARTICIPATE` | Oracle < DEX by ≥ min-discount — deposit STX to acquire sBTC below market | | `MONITOR` | Spread present but below threshold — watch and retry | | `WAIT_FOR_DEPOSIT_PHASE` | Cycle is in buffer or settle phase — deposits closed | | `NO_SBTC_AVAILABLE` | No sBTC deposited in current cycle — nothing to acquire | Confidence: - `high` — discount ≥ 2% or clearly unfavourable - `medium` — discount 1–2% - `low` — borderline ## Technical notes - Contract: `SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-stx-jing-v2` (v2, current; v1 was on cycle 5) - DLMM price formula: `STX/sBTC = 1e10 / dlmmRaw` (contract stores inverse ratio) - XYK price formula: `STX/sBTC = xykRaw / 1e8` (contract stores direct ratio with 1e8 scale) - Oracle price: Pyth Hermes `BTC/USD ÷ STX/USD = STX/sBTC` - No API key required for any data source - All Hiro reads use sender `SP000000000000000000002Q6VF78` (burn address, valid for read-only calls) ## Output contract All outputs are JSON to stdout. **Error:** ```json { "error": "descriptive message" } ``` ## Origin Winner of AIBTC x Bitflow Skills Pay the Bills competition. Original author: @teflonmusk Competition PR: https://github.com/BitflowFinance/bff-skills/pull/78