QuickSwap V3 DEX

What this skill does

## Pre-flight Dependencies (auto-injected by Plugin Store CI)

> Run once per session before first use. These checks ensure required tools are installed.

### Version check (auto-injected)

> **AI Agent Instruction**: Run this version check before executing any commands from this skill. The check is a read-only fetch from `raw.githubusercontent.com` — it does **not** install anything. If it reports `Update available`, you MUST stop, surface the message to the user verbatim, and obtain explicit confirmation before running the suggested `npx skills add …` command. Do not run the update silently. After a confirmed update completes, re-read this SKILL.md before proceeding.

```bash
# Check for skill updates (1-hour cache).
# Network scope: this block calls raw.githubusercontent.com for the version probe only.
# It does NOT install anything; install requires user-confirmed `npx skills add` below.
UPDATE_CACHE="$HOME/.plugin-store/update-cache/quickswap-plugin"
CACHE_MAX=3600
LOCAL_VER="0.1.2"
DO_CHECK=true

if [ -f "$UPDATE_CACHE" ]; then
  CACHE_MOD=$(stat -f %m "$UPDATE_CACHE" 2>/dev/null || stat -c %Y "$UPDATE_CACHE" 2>/dev/null || echo 0)
  NOW=$(date +%s)
  AGE=$(( NOW - CACHE_MOD ))
  [ "$AGE" -lt "$CACHE_MAX" ] && DO_CHECK=false
fi

if [ "$DO_CHECK" = true ]; then
  REMOTE_VER=$(curl -sf --max-time 3 "https://raw.githubusercontent.com/okx/plugin-store/main/skills/quickswap-plugin/plugin.yaml" | grep '^version' | head -1 | tr -d '"' | awk '{print $2}')
  if [ -n "$REMOTE_VER" ]; then
    mkdir -p "$HOME/.plugin-store/update-cache"
    echo "$REMOTE_VER" > "$UPDATE_CACHE"
  fi
fi

REMOTE_VER=$(cat "$UPDATE_CACHE" 2>/dev/null || echo "$LOCAL_VER")
if [ "$REMOTE_VER" != "$LOCAL_VER" ]; then
  echo "Update available: quickswap-plugin v$LOCAL_VER -> v$REMOTE_VER."
  echo "ACTION REQUIRED: ask the user to confirm before running:"
  echo "  npx skills add okx/plugin-store --skill quickswap-plugin --global"
  echo "(This contacts the npm registry and github.com/okx/plugin-store and overwrites this skill. Do NOT auto-run.)"
fi
```

### Install onchainos CLI + Skills (auto-injected)

```bash
# 1. Install onchainos CLI — pin to latest release tag, verify SHA256
#    of the installer before executing (no curl|sh from main).
if ! command -v onchainos >/dev/null 2>&1; then
  set -e
  LATEST_TAG=$(curl -sSL --max-time 5 \
    "https://api.github.com/repos/okx/onchainos-skills/releases/latest" \
    | sed -n 's/.*"tag_name"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p' | head -1)
  if [ -z "$LATEST_TAG" ]; then
    echo "ERROR: failed to resolve latest onchainos release tag (network or rate limit)." >&2
    echo "       Manual install: https://github.com/okx/onchainos-skills" >&2
    exit 1
  fi

  ONCHAINOS_TMP=$(mktemp -d)
  curl -sSL --max-time 30 \
    "https://raw.githubusercontent.com/okx/onchainos-skills/${LATEST_TAG}/install.sh" \
    -o "$ONCHAINOS_TMP/install.sh"
  curl -sSL --max-time 30 \
    "https://github.com/okx/onchainos-skills/releases/download/${LATEST_TAG}/installer-checksums.txt" \
    -o "$ONCHAINOS_TMP/installer-checksums.txt"

  EXPECTED=$(awk '$2 ~ /install\.sh$/ {print $1; exit}' "$ONCHAINOS_TMP/installer-checksums.txt")
  if command -v sha256sum >/dev/null 2>&1; then
    ACTUAL=$(sha256sum "$ONCHAINOS_TMP/install.sh" | awk '{print $1}')
  else
    ACTUAL=$(shasum -a 256 "$ONCHAINOS_TMP/install.sh" | awk '{print $1}')
  fi
  if [ -z "$EXPECTED" ] || [ "$EXPECTED" != "$ACTUAL" ]; then
    echo "ERROR: onchainos installer SHA256 mismatch — refusing to execute." >&2
    echo "       expected=$EXPECTED  actual=$ACTUAL  tag=$LATEST_TAG" >&2
    rm -rf "$ONCHAINOS_TMP"
    exit 1
  fi

  sh "$ONCHAINOS_TMP/install.sh"
  rm -rf "$ONCHAINOS_TMP"
  set +e
fi

# 2. Install onchainos skills (enables AI agent to use onchainos commands)
npx skills add okx/onchainos-skills --yes --global

# 3. Install plugin-store skills (enables plugin discovery and management)
npx skills add okx/plugin-store --skill plugin-store --yes --global
```

---


# QuickSwap V3 DEX

QuickSwap V3 is the leading concentrated liquidity DEX on Polygon, built on the **Algebra Protocol** (not Uniswap V3). Key difference: no fee tier parameter — fees are dynamic per pool.

**Chain:** Polygon (137)
**Contracts:**
- SwapRouter: `0xf5b509bb0909a69b1c207e495f687a596c168e12`
- Quoter: `0xa15F0D7377B2A0C0c10db057f641beD21028FC89`
- Factory: `0x411b0fAcC3489691f28ad58c47006AF5E3Ab3A28`

---

## Pre-flight Dependencies

Before using this plugin, verify both dependencies are working:

```bash
# 1. Verify plugin binary
quickswap-plugin --version
# Expected: quickswap-plugin 0.1.2

# 2. Verify onchainos wallet is configured for Polygon
onchainos wallet addresses --chain 137
# Expected: JSON with at least one address
```

If `onchainos wallet addresses` returns no addresses, configure a Polygon wallet first before proceeding.

---

## Data Trust Boundary

| Source | Used For | Trust Level |
|--------|----------|-------------|
| Polygon RPC (`polygon.publicnode.com`) | Token balances, decimals, allowances, quotes | On-chain — authoritative |
| QuickSwap subgraph (`api.thegraph.com`) | Pool TVL and volume rankings | Off-chain indexer — informational only |
| onchainos CLI | Token resolution, tx broadcast | Local CLI — trusted |

**Rule:** Never use subgraph data for trade execution amounts. All swap parameters (amountIn, amountOut, slippage) are derived from on-chain Quoter calls only.

> ⚠️ **Partial-state risk**: `swap --confirm` executes up to 3 sequential transactions (wrap → approve → swap). If a transaction confirms but the binary times out waiting for the next (60-second poll), the swap halts mid-sequence. In that case: check your WMATIC/token balance to determine what was completed, then re-run the command — the approve step is idempotent (skipped if allowance is sufficient). Do not resubmit without checking state first.

---

## Proactive Onboarding

When a user signals they are **new or just installed** this plugin — e.g. "I just installed quickswap-plugin", "how do I swap on Polygon", "what can I do with this" — **do not wait for them to ask specific questions.** Proactively walk them through the Quickstart in order, one step at a time, waiting for confirmation before proceeding to the next:

1. **Check wallet** — run `onchainos wallet addresses --chain 137`. If no address, direct them to connect via `onchainos wallet login`. Do not proceed to write operations until a wallet is confirmed.
2. **Check balance** — run `onchainos wallet balance --chain 137`. The user needs POL/MATIC for gas (~0.01 POL) plus the token they want to swap. If balance is zero, explain how to bridge via a CEX or cross-chain bridge.
3. **Token address tip** — explain that QuickSwap has two USDC tokens: **USDC.e** (`0x2791Bca1...4174`, bridged, more liquid) and native **USDC** (`0x3c499c...3359`, CCTP-bridged). Use the full address to be unambiguous.
4. **Get a quote first** — run `quickswap-plugin quote --token-in <address> --token-out <address> --amount <amount>` so the user sees the expected output before committing.
5. **Preview the swap** — run `quickswap-plugin swap` without `--confirm` so the user sees all steps (approve, swap) and calldata.
6. **Execute** — once they confirm, re-run with `--confirm`.

Do not dump all steps at once. Guide conversationally — confirm each step before moving on.

---

## Quickstart

New to QuickSwap V3? Follow these steps to go from zero to your first swap on Polygon.

### Step 1 — Connect wallet

```bash
onchainos wallet login [email protected]
onchainos wallet addresses --chain 137
```

### Step 2 — Check balances

```bash
onchainos wallet balance --chain 137
```

You need POL/MATIC for gas (~0.01 POL per swap). If balance is zero, bridge from a CEX or use a cross-chain bridge.

### Step 3 — Browse top pools

```bash
quickswap-plugin pools --limit 10
```

This shows the most liquid QuickSwap V3 pairs. When the subgraph is available it includes TVL and volume; otherwise shows t