# Jingswap — Full Reference

> Blind batch auctions for sBTC swaps on Bitcoin L2. Zero slippage, zero MEV, zero front-running.

## Overview

Jingswap is a blind batch auction protocol on the Stacks blockchain. It enables trustless swaps between sBTC and STX (or USDCx) through periodic auction cycles. Depositors on both sides submit funds blindly, and settlement occurs at an oracle-determined clearing price — ensuring fair execution with no front-running.

## The Problem

DEX swaps on Stacks suffer from slippage, front-running, and thin liquidity for large orders. Jingswap solves this with batch auctions: all deposits in a cycle settle at the same oracle price, eliminating MEV and providing predictable execution.

## Markets

| Market | Contract | Pair |
|--------|----------|------|
| sBTC/STX | SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-stx-jing-v2 | sBTC <> STX |
| sBTC/USDCx | SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-usdcx-jing-v2 | sBTC <> USDCx |

Both markets use the same auction mechanism and are accessible through the same MCP tools and skills (pass `market: "sbtc-usdcx"` to switch from the default `sbtc-stx`).

## How Auction Cycles Work

Each cycle has three phases:

### Phase 0: Deposit (~5 minutes minimum)
- Users deposit sBTC or STX/USDCx into the current cycle
- Minimum: 1 STX and 1,000 sats sBTC on each side
- Deposits stay open until someone calls `close-deposits` (after 150 blocks)
- Users can cancel deposits anytime during this phase

### Phase 1: Buffer (~1 minute)
- 30-block cooldown after deposits close
- No actions possible — prevents last-second manipulation
- This is what makes Jing "blind" — any price visible during deposits is guaranteed stale by settlement

### Phase 2: Settlement
- Anyone can trigger settlement using Pyth oracle prices
- `settle-with-refresh` fetches fresh Pyth VAAs and settles in one transaction
- Clearing price is determined by BTC/USD and STX/USD oracle feeds
- Both sides receive their swapped tokens proportionally
- Unswapped remainder rolls automatically into the next cycle
- A 0.1% fee goes to the treasury

### Safety Valve: Cancel Cycle
- If settlement fails for 530 blocks (~17.5 min), anyone can cancel the cycle
- All deposits roll into the next cycle (no funds lost)
- Users can individually cancel during the next deposit phase

## Safety Gates

Settlement only proceeds if three gates pass:
1. **Freshness**: Pyth price must be < 60 seconds old
2. **Confidence**: Pyth confidence interval must be < 2%
3. **Divergence**: Oracle price must be within 10% of the on-chain DEX price

If any gate fails, settlement waits until conditions normalize.

## FAQ

Q: What is Jing Swap?
A: Jing Swap is a blind batch auction DEX for sBTC swaps on Stacks. Depositors commit funds before the settlement price is known, then everyone settles at the same Pyth oracle spot price. Zero slippage, zero MEV, zero front-running.

Q: How is Jing different from a DEX?
A: On any DEX — whether constant-product (Uniswap v2) or concentrated liquidity — larger trades move the price against you and are vulnerable to MEV. Jing sidesteps this entirely: all depositors settle at the same Pyth oracle spot price in a single batch. No price impact, no sandwich attacks, and the settlement price is unknown at deposit time.

Q: How does a swap cycle work?
A: Each cycle has phases: Deposit (lock sBTC or STX, stays open until someone calls close-deposits after 150+ blocks), Buffer (30 blocks of silence so stale prices expire), then Settle (anyone calls settle, Pyth oracle price is read, tokens are distributed pro-rata). Unfilled amounts auto-roll to the next cycle.

Q: What are the safety gates?
A: Settlement only proceeds if three gates pass: Pyth price must be fresh (< 60s), Pyth confidence must be tight (< 2%), and the oracle price must be within 10% of the on-chain DEX price. If any gate fails, settlement waits until conditions normalize.

Q: Why is there a buffer before settlement?
A: After deposits close, there's a 30-block buffer (~60s) where no actions are allowed. This is what makes Jing "blind" — the Pyth price must be less than 60 seconds old at the time of the settlement block, so any price that was visible during the deposit phase is guaranteed stale by the time settlement opens. The settler must push a fresh Pyth price that nobody could have seen when depositing.

Q: Could the buffer be removed?
A: Since the settlement price comes from the Pyth oracle (off-chain exchange data, essentially impossible to manipulate on-chain), the buffer is less about preventing price manipulation and more about preventing timing games. Without it, someone could see all deposits, then front-run the settle transaction with a Bitflow/DLMM trade to profit from the known imbalance. The buffer also prevents the settler from cherry-picking the most favorable Pyth price tick — the price is determined by whatever Pyth reports ~60 seconds after deposits close (30 blocks at ~2s each), which no depositor could have known at deposit time. Removing it would be defensible given how hard Pyth is to manipulate, but you'd lose the timing-game protection. Jing doesn't compete on speed — it competes on integrity. Whales and stacking pools need robust, manipulation-proof settlement, not millisecond execution. One minute of patience is a small price for that guarantee.

Q: Can I cancel my deposit?
A: During the deposit phase, yes — cancel anytime with no penalty. Once deposits close, your funds are locked for settlement.

Q: What if settlement keeps failing?
A: Settlement fails if any of the three safety gates fails — Pyth confidence wider than 2%, the price being stale (> 60s), or the oracle price diverging more than 10% from the on-chain DEX price. Anyone can retry settle() and conditions usually normalize within minutes. If settlement still hasn't succeeded after ~500 blocks (~16 min), anyone can call cancel-cycle. All deposits roll over to the next cycle, and users can withdraw (get a refund) during the next deposit phase. No funds are ever stuck.

Q: Do I need to claim my tokens after settlement?
A: No. Settlement pushes tokens directly to your wallet — there's no claim step. Once the cycle settles, the swapped tokens are already yours.

Q: What if the pool is full?
A: Each side (STX and sBTC) has 50 deposit slots. If all 50 are taken, you can still deposit — but your amount must be larger than the smallest existing deposit. That smallest depositor gets refunded instantly and you take their slot. This keeps the pool open to serious participants and prevents dust spam.

Q: Why do stacking pools need Jing?
A: Stacking pools like STX Juice and FastPool need to swap large amounts of sBTC to STX every 2 weeks when rewards come in. Today they do this off-chain — paying 1-2% in slippage on centralized exchanges. With Jing, they can swap on-chain at the oracle price with zero slippage. It's non-custodial, transparent, and verifiable — no more trusting that the pool operator got you the best rate.

Q: Can AI agents use Jing?
A: Yes. Jing is integrated into the aibtc-dev toolkit — both as MCP tools (15 tools) and CLI skills (15 subcommands). Any AI agent can deposit, cancel, and settle through these interfaces. Because settlement is MEV-proof and the price is oracle-determined, agents can swap without getting sandwiched.

Q: Where are the smart contracts?
A: The current market contracts are sbtc-stx-jing-v2 and sbtc-usdcx-jing-v2 by SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22. The previous contracts (sbtc-stx-jing, sbtc-usdcx-jing, sbtc-stx-jingswap, sbtc-usdcx-jingswap) are retired but their history is preserved on-chain.

Q: What is a Drip strategy?
A: A premium feature for large holders. A dedicated contract is deployed where only you can withdraw. A keeper drips your position across many auction cycles over days or weeks — like a self-custodied TWAP order. No market impact, trustless custody.

Q: Is Jing Swap open source?
A: Yes. All smart contracts are fully open source and publicly available for review. Inspired by CoW Protocol batch auctions, adapted for Stacks.

Q: Who built Jing Swap?
A: Jing Swap is built by RaphaStacks and the Stacks community. It is an independent project with no VC funding or token sale.

## Smart Contracts

- **Language**: Clarity (decidable, non-Turing-complete)
- **Oracle**: Pyth Network via `SP1CGXWEAMG6P6FT04W66NVGJ7PQWMDAC19R7PJ0Y.pyth-storage-v4`
- **sBTC**: `SM3VDXK3WZZSA84XXFKAFAF15NNZX32CTSG82JFQ4.sbtc-token`
- **Max depositors**: 50 per side per cycle

## Timing (Nakamoto)

- Stacks blocks: ~2 seconds each
- Deposit minimum: 150 blocks (~5 minutes)
- Buffer: 30 blocks (~1 minute)
- Cancel threshold: 530 blocks (~17.5 minutes) from close

## Price Sources

| Source | Description |
|--------|-------------|
| Pyth Oracle | BTC/USD and STX/USD — used for settlement clearing price |
| XYK Pool | On-chain AMM pool (SM1793C4R5PZ4NS4VQ4WMP7SKKYVH8JZEWSZ9HCCR) — reference price |
| DLMM | Concentrated liquidity pool — reference price |

## AI Agent Integration

Jingswap is fully accessible to AI agents through two interfaces:

### aibtc MCP Server (15 tools)

Install: `npx @aibtc/mcp-server@latest --install`

All tools accept an optional `market` parameter: `"sbtc-stx"` (default) or `"sbtc-usdcx"`.

| Tool | Type | Description |
|------|------|-------------|
| `jingswap_get_cycle_state` | Read | Current phase, blocks elapsed, totals, minimums |
| `jingswap_get_depositors` | Read | STX/USDCx and sBTC depositors for a cycle |
| `jingswap_get_user_deposit` | Read | User deposit amounts for a cycle |
| `jingswap_get_settlement` | Read | Settlement details (clearing price, fees) |
| `jingswap_get_cycles_history` | Read | Full history of all cycles |
| `jingswap_get_user_activity` | Read | User deposits, cancellations, fills |
| `jingswap_get_prices` | Read | Oracle + DEX prices (XYK, DLMM, Pyth) |
| `jingswap_deposit_stx` | Write | Deposit STX or USDCx (deposit phase only) |
| `jingswap_deposit_sbtc` | Write | Deposit sBTC in sats (deposit phase only) |
| `jingswap_cancel_stx` | Write | Cancel STX/USDCx deposit (deposit phase only) |
| `jingswap_cancel_sbtc` | Write | Cancel sBTC deposit (deposit phase only) |
| `jingswap_close_deposits` | Write | Close deposit phase to buffer phase |
| `jingswap_settle` | Write | Settle with stored prices (usually stale) |
| `jingswap_settle_with_refresh` | Write | Settle with fresh Pyth VAAs (recommended) |
| `jingswap_cancel_cycle` | Write | Safety valve — rolls deposits to next cycle |

### aibtc Skills (15 CLI subcommands)

Usage: `bun run jingswap/jingswap.ts <subcommand> [options]`

All subcommands accept `--market sbtc-usdcx` to switch from the default sbtc-stx market.

| Subcommand | Type | Description |
|------------|------|-------------|
| `cycle-state` | Read | Current phase, blocks elapsed, totals, minimums |
| `depositors` | Read | STX/USDCx and sBTC depositors for a cycle |
| `user-deposit` | Read | User deposit amounts for a cycle |
| `settlement` | Read | Settlement details (clearing price, fees) |
| `cycles-history` | Read | Full history of all cycles |
| `user-activity` | Read | User deposits, cancellations, fills |
| `prices` | Read | Oracle + DEX prices (XYK, DLMM, Pyth) |
| `deposit-stx` | Write | Deposit STX or USDCx (deposit phase only) |
| `deposit-sbtc` | Write | Deposit sBTC in sats (deposit phase only) |
| `cancel-stx` | Write | Cancel STX/USDCx deposit |
| `cancel-sbtc` | Write | Cancel sBTC deposit |
| `close-deposits` | Write | Close deposit phase |
| `settle` | Write | Settle with stored prices |
| `settle-with-refresh` | Write | Settle with fresh Pyth VAAs (recommended) |
| `cancel-cycle` | Write | Safety valve — rolls deposits to next cycle |

### API Endpoints

Base URL: Backend API (requires `x-api-key` header)

- `GET /api/auction/cycle-state`
- `GET /api/auction/depositors/:cycle`
- `GET /api/auction/deposit/:cycle/:address`
- `GET /api/auction/settlement/:cycle`
- `GET /api/auction/cycles-history`
- `GET /api/auction/activity/:address`
- `GET /api/auction/pyth-prices`
- `GET /api/auction/dex-price`
- `GET /api/auction/pyth-vaas`

## Post Conditions

- **Deposit tools**: `PostConditionMode.Deny` with exact amount checks
- **Cancel/settle/cancel-cycle**: `PostConditionMode.Allow` — post conditions are variable depending on depositor list, but nothing leaves the caller's wallet

## Links

- Website: https://www.jingswap.com
- X/Twitter: https://x.com/JingSwap
- AI Tools: https://www.jingswap.com/ai-tools
- sBTC/STX contract: https://explorer.hiro.so/txid/SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-stx-jing-v2?chain=mainnet
- sBTC/USDCx contract: https://explorer.hiro.so/txid/SPV9K21TBFAK4KNRJXF5DFP8N7W46G4V9RCJDC22.sbtc-usdcx-jing-v2?chain=mainnet
- MCP PR: https://github.com/aibtcdev/aibtc-mcp-server/pull/327
- Skills PR: https://github.com/aibtcdev/skills/pull/162