From 3ce5d21d5c606d2d4fd71cd88d056c5335f26adf Mon Sep 17 00:00:00 2001 From: Grayson Ho Date: Mon, 11 May 2026 21:59:23 +0100 Subject: [PATCH 1/3] feat: add zerion-uniswap-lp and zerion-uniswap-x402 partner skills Two partner skills pairing Uniswap AI workflows with Zerion CLI: - zerion-uniswap-lp: portfolio + PnL context before sizing a Uniswap v4 LP position via /liquidity-planner - zerion-uniswap-x402: cross-chain balance check + bridge before paying an HTTP 402 challenge via /pay-with-any-token Bridge commands use canonical signature `zerion bridge `. Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/zerion-uniswap-lp/SKILL.md | 71 +++++++++++++++++++++++++++++ skills/zerion-uniswap-x402/SKILL.md | 64 ++++++++++++++++++++++++++ 2 files changed, 135 insertions(+) create mode 100644 skills/zerion-uniswap-lp/SKILL.md create mode 100644 skills/zerion-uniswap-x402/SKILL.md diff --git a/skills/zerion-uniswap-lp/SKILL.md b/skills/zerion-uniswap-lp/SKILL.md new file mode 100644 index 00000000..5465929b --- /dev/null +++ b/skills/zerion-uniswap-lp/SKILL.md @@ -0,0 +1,71 @@ +--- +name: zerion-uniswap-lp +description: > + Plan Uniswap v4 LP positions using Zerion CLI portfolio data and PnL to size + exposure correctly before deploying capital via the Uniswap /liquidity-planner skill. +license: MIT +--- + +# Uniswap LP Planning with Portfolio Context + +**Purpose:** Use Zerion CLI to assess current exposure and PnL before sizing a Uniswap LP position with `/liquidity-planner`, so the agent deploys capital with full portfolio context. + +## Key Commands + +**Uniswap skill (invoke in agent context):** +- `/liquidity-planner` — plans LP positions and generates Uniswap interface deep links + +**Zerion CLI (shell):** +- `zerion positions
` — current token and DeFi positions by chain +- `zerion pnl
` — profit and loss per wallet and per asset +- `zerion portfolio
` — total portfolio value and top holdings +- `zerion bridge ` — move capital to the target chain for LP deployment + +## Requirements + +- Uniswap AI skills: `npx skills add Uniswap/uniswap-ai` +- Zerion CLI: `npx -y zerion-cli init -y --browser` +- Zerion API key: `export ZERION_API_KEY="zk_..."` + +## Workflow + +### 1. Check current positions across all chains +```bash +zerion positions $WALLET +``` +Understand what the agent already holds and where, so LP sizing doesn't over-concentrate exposure. + +### 2. Review PnL before committing capital +```bash +zerion pnl $WALLET +``` +Check unrealized gains and losses per asset. Avoid deploying into a pool with an asset already deep in loss. + +### 3. Confirm total portfolio value +```bash +zerion portfolio $WALLET +``` +Validate the proportion of total portfolio the intended LP position represents. + +### 4. Bridge capital to the target chain if needed +```bash +zerion bridge ethereum ETH 1 base ETH --cheapest +``` +Move tokens to the chain where the LP pool lives before planning. Signature: `zerion bridge `. + +### 5. Plan the LP position +Invoke the Uniswap skill in your agent context: +``` +/liquidity-planner +``` +The skill generates the LP position plan and interface deep link based on your inputs (pool, fee tier, range). + +## Common Blockers + +- **LP size too large relative to portfolio** — re-check `zerion portfolio` and reduce the intended deposit amount +- **Capital on wrong chain** — `zerion positions` shows chain breakdown; bridge first with `zerion bridge` before planning +- **Asset already at a loss** — `zerion pnl` will surface this; consider whether IL risk compounds an existing losing position + +## Related Skills + +- **zerion-uniswap-x402** — pay x402 HTTP 402 challenges with cross-chain funding via Zerion CLI \ No newline at end of file diff --git a/skills/zerion-uniswap-x402/SKILL.md b/skills/zerion-uniswap-x402/SKILL.md new file mode 100644 index 00000000..1dfac25e --- /dev/null +++ b/skills/zerion-uniswap-x402/SKILL.md @@ -0,0 +1,64 @@ +--- +name: zerion-uniswap-x402 +description: > + Pay HTTP 402 (x402) payment challenges using any token via Uniswap swaps, + with Zerion CLI handling cross-chain balance checks and bridging beforehand. +license: MIT +--- + +# Uniswap x402 Payments with Cross-Chain Funding + +**Purpose:** Use Zerion CLI to verify and position capital across chains, then pay HTTP 402 challenges in any token using the Uniswap `/pay-with-any-token` skill. + +## Key Commands + +**Uniswap skill (invoke in agent context):** +- `/pay-with-any-token` — pays an x402 or MPP HTTP 402 challenge by swapping tokens via Uniswap + +**Zerion CLI (shell):** +- `zerion positions
` — check token balances by chain +- `zerion bridge ` — move capital to the required chain +- `zerion portfolio
` — verify post-bridge balance before paying + +## Requirements + +- Uniswap AI skills: `npx skills add Uniswap/uniswap-ai` +- Zerion CLI: `npx -y zerion-cli init -y --browser` +- An x402-compatible endpoint to pay (see [x402 docs](https://x402.org)) + +## Workflow + +### 1. Check agent wallet balances by chain +```bash +zerion positions $AGENT_WALLET +``` +Identify which chain holds sufficient liquidity for the payment. + +### 2. Bridge to the required chain if needed +```bash +zerion bridge ethereum USDC 50 base USDC --cheapest +``` +Move capital to the chain where the x402 challenge is denominated. Signature: `zerion bridge `. + +### 3. Verify the balance landed +```bash +zerion portfolio $AGENT_WALLET +``` +Confirm the bridge completed and the target chain balance is sufficient before proceeding. + +### 4. Pay the x402 challenge +Invoke the Uniswap skill in your agent context: +``` +/pay-with-any-token +``` +The skill handles token selection, swap routing, and payment submission via Uniswap. + +## Common Blockers + +- **Insufficient balance after bridge** — bridges can take 1–3 minutes; re-run `zerion portfolio` to confirm arrival before invoking `/pay-with-any-token` +- **Wrong chain** — `zerion positions` shows balances per chain; ensure you bridge to the chain the x402 endpoint requires +- **Bridge tx pending** — run `zerion history $AGENT_WALLET` to check bridge transaction status + +## Related Skills + +- **zerion-uniswap-lp** — deploy Uniswap LP positions after positioning capital with Zerion CLI From 23a3e2ba26395a960726e6043dad21991594775b Mon Sep 17 00:00:00 2001 From: Grayson Ho Date: Tue, 12 May 2026 09:58:16 +0100 Subject: [PATCH 2/3] fix(skills): prefix somnia skill names with zerion- Co-Authored-By: Claude Opus 4.7 (1M context) --- skills/zerion-somnia-blockchain/SKILL.md | 2 +- skills/zerion-somnia-reactivity/SKILL.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/skills/zerion-somnia-blockchain/SKILL.md b/skills/zerion-somnia-blockchain/SKILL.md index 9b231818..f1c7f2a8 100644 --- a/skills/zerion-somnia-blockchain/SKILL.md +++ b/skills/zerion-somnia-blockchain/SKILL.md @@ -1,5 +1,5 @@ --- -name: somnia-blockchain +name: zerion-somnia-blockchain description: Comprehensive Somnia blockchain knowledge — network info, unique features, gas model, and deployment guidance for building on Somnia --- diff --git a/skills/zerion-somnia-reactivity/SKILL.md b/skills/zerion-somnia-reactivity/SKILL.md index 780debf1..21a69d59 100644 --- a/skills/zerion-somnia-reactivity/SKILL.md +++ b/skills/zerion-somnia-reactivity/SKILL.md @@ -1,5 +1,5 @@ --- -name: somnia-reactivity +name: zerion-somnia-reactivity description: Deep-dive reference for Somnia Reactivity — the native event-driven pub/sub system. Covers off-chain WebSocket subscriptions, on-chain Solidity handlers, subscription creation from both TypeScript and Solidity, gas configuration, system events (BlockTick/Schedule), and troubleshooting. Use when the user is building reactive dApps, creating subscriptions, writing handler contracts, or debugging reactivity issues. --- From 92d09cd0aed0d6ee191006b4f9ee6c20d3e55582 Mon Sep 17 00:00:00 2001 From: Grayson Ho Date: Wed, 13 May 2026 20:04:23 +0100 Subject: [PATCH 3/3] Update SKILL.md --- skills/zerion-uniswap-x402/SKILL.md | 83 +++++++++++++++++++++++------ 1 file changed, 66 insertions(+), 17 deletions(-) diff --git a/skills/zerion-uniswap-x402/SKILL.md b/skills/zerion-uniswap-x402/SKILL.md index 1dfac25e..9a8c493f 100644 --- a/skills/zerion-uniswap-x402/SKILL.md +++ b/skills/zerion-uniswap-x402/SKILL.md @@ -2,47 +2,87 @@ name: zerion-uniswap-x402 description: > Pay HTTP 402 (x402) payment challenges using any token via Uniswap swaps, - with Zerion CLI handling cross-chain balance checks and bridging beforehand. + with Zerion CLI handling cross-chain balance checks and optional bridging beforehand. license: MIT --- # Uniswap x402 Payments with Cross-Chain Funding -**Purpose:** Use Zerion CLI to verify and position capital across chains, then pay HTTP 402 challenges in any token using the Uniswap `/pay-with-any-token` skill. +**Purpose:** Use Zerion CLI to verify and optionally position capital across chains, then pay x402 HTTP 402 challenges in any token using the Uniswap `/pay-with-any-token` skill. + +> **Scope:** This skill covers x402 only. MPP/Tempo is out of scope. ## Key Commands **Uniswap skill (invoke in agent context):** -- `/pay-with-any-token` — pays an x402 or MPP HTTP 402 challenge by swapping tokens via Uniswap +- `/pay-with-any-token` — pays an x402 HTTP 402 challenge by swapping tokens via Uniswap **Zerion CLI (shell):** - `zerion positions
` — check token balances by chain -- `zerion bridge ` — move capital to the required chain -- `zerion portfolio
` — verify post-bridge balance before paying +- `zerion bridge --to-address
--cheapest` — optionally pre-position capital to the signing wallet +- `zerion portfolio
` — verify balance before paying ## Requirements - Uniswap AI skills: `npx skills add Uniswap/uniswap-ai` - Zerion CLI: `npx -y zerion-cli init -y --browser` +- Zerion API key: `export ZERION_API_KEY="zk_..."` +- Uniswap API key: `export UNISWAP_API_KEY="..."` +- `cast` (Foundry): `curl -L https://foundry.paradigm.xyz | bash && foundryup` +- `jq`: `brew install jq` / `apt install jq` - An x402-compatible endpoint to pay (see [x402 docs](https://x402.org)) +## Wallet Setup + +> **Critical:** `/pay-with-any-token` signs EIP-3009 using the wallet referenced by your keystore or `PRIVATE_KEY` env var. Zerion CLI manages its own wallet separately. For the flow to work end-to-end, both must point to the same key. + +**Import your EVM key into Zerion CLI:** +```bash +zerion wallet import --evm-key +``` + +**Import the same key into cast (recommended — encrypted keystore, no plaintext in env):** +```bash +cast wallet import --interactive +``` +Zerion CLI encrypts keys via OpenWallet. Using cast keystore keeps both layers encrypted and avoids exposing a raw key in the environment. + +If using `PRIVATE_KEY` directly instead: +```bash +export PRIVATE_KEY=0x... # plaintext — only use in trusted environments +``` + +Set your signing wallet address: +```bash +export WALLET= +``` + ## Workflow ### 1. Check agent wallet balances by chain ```bash -zerion positions $AGENT_WALLET +zerion positions $WALLET ``` -Identify which chain holds sufficient liquidity for the payment. +Identify which chain holds sufficient liquidity. If balance is sufficient on the target chain, skip to step 4 — `/pay-with-any-token` will source funds itself. + +### 2. (Optional) Pre-position capital with Zerion CLI + +Two paths — choose one: -### 2. Bridge to the required chain if needed +**Path A — Pre-bridge with Zerion CLI:** ```bash -zerion bridge ethereum USDC 50 base USDC --cheapest +zerion bridge USDC base 50 --to-address $WALLET --cheapest ``` -Move capital to the chain where the x402 challenge is denominated. Signature: `zerion bridge `. +Funds land in the signing wallet on the target chain. Use `--cheapest` to minimise bridge fees. -### 3. Verify the balance landed +**Path B — Skip the bridge:** +Let `/pay-with-any-token` handle funding via its internal phase 4a/4b sourcing. No Zerion bridge step needed. + +> If you pre-bridge (Path A), the trading API funding phase does not run. If you skip (Path B), `/pay-with-any-token` sources funds itself. Both paths work — pre-bridging gives you explicit control; skipping is simpler if funds are already available. + +### 3. Verify balance (Path A only) ```bash -zerion portfolio $AGENT_WALLET +zerion portfolio $WALLET ``` Confirm the bridge completed and the target chain balance is sufficient before proceeding. @@ -51,14 +91,23 @@ Invoke the Uniswap skill in your agent context: ``` /pay-with-any-token ``` -The skill handles token selection, swap routing, and payment submission via Uniswap. +The skill handles token selection, swap routing, EIP-3009 signing, and payment submission. + +## Reference Behavior + +Validate end-to-end behavior against: +[`evals/suites/pay-with-any-token/cases/x402-detection-probe.md`](https://github.com/Uniswap/uniswap-ai/blob/main/evals/suites/pay-with-any-token/cases/x402-detection-probe.md) + +Future changes on either side should be tested against this eval case. ## Common Blockers -- **Insufficient balance after bridge** — bridges can take 1–3 minutes; re-run `zerion portfolio` to confirm arrival before invoking `/pay-with-any-token` -- **Wrong chain** — `zerion positions` shows balances per chain; ensure you bridge to the chain the x402 endpoint requires -- **Bridge tx pending** — run `zerion history $AGENT_WALLET` to check bridge transaction status +- **Two separate wallets** — most common failure. Ensure `zerion wallet import --evm-key` and your cast keystore or `PRIVATE_KEY` all reference the same key +- **Insufficient balance after bridge** — bridges can take 1–3 minutes; re-run `zerion portfolio $WALLET` to confirm arrival before invoking `/pay-with-any-token` +- **Wrong chain** — `zerion positions` shows balances per chain; ensure the signing wallet holds funds on the chain the x402 endpoint requires +- **Bridge tx pending** — run `zerion history $WALLET` to check bridge transaction status +- **Missing `jq` or `cast`** — `/pay-with-any-token` requires both; install before running ## Related Skills -- **zerion-uniswap-lp** — deploy Uniswap LP positions after positioning capital with Zerion CLI +- **zerion-uniswap-lp** — plan Uniswap LP positions using Zerion CLI portfolio context \ No newline at end of file