@continuumdao/ctm-mpc-defi 0.2.2 → 0.2.4

package/dist/agent/skills/aave-v4/SKILL.md

@@ -1,43 +1,149 @@
 ---
 name: aave-v4
-description: Aave v4 Spoke supply, withdraw, borrow, and repay via Continuum MPC multiSignRequest tools.
+description: Aave v4 lending and borrowing via Continuum MPC — hubs, spokes, supply, withdraw, borrow, repay.
 ---
 
 # Aave v4 (MCP)
 
+Aave v4 organizes liquidity into **hubs** (market segments) and **spokes** (on-chain contracts you call). Each reserve (e.g. WETH, USDC) is listed in a hub and executed through that reserve’s spoke.
+
+## Architecture (explain this to users)
+
+| Concept | What it is | Agent needs to know |
+|---------|------------|---------------------|
+| **Hub** | Off-chain market segment (Core, Plus, Prime) | Maps to UI `marketId`: `main` → Plus, `core` → Core, `bluechip` → Prime |
+| **Spoke** | On-chain contract (`supply`, `withdraw`, `borrow`, `repay`) | **Do not guess.** The MCP server resolves spoke from the Aave v4 API using `chainId` + `underlying` + `marketId` |
+| **Reserve** | One asset in one hub (underlying + APY + spoke) | Use `get_defi_protocol_supported_tokens` for valid underlyings |
+| **Position** | User’s supplies/debt on a spoke | Withdraw/borrow/repay risk depends on health factor on that spoke |
+
+**Important:** The UI market (`main`) and the hub that lists an asset can differ. Example on Ethereum: WETH is in **Core**, not Plus, even when the user picks “main”. The server auto-picks the hub that actually lists the asset.
+
 ## Before any action
 
 1. `load_defi_protocol({ protocolId: "aave-v4" })`
-2. `get_defi_protocol_supported_chains` — intersect with `get_chain_registry` (node must have RPC)
-3. `get_defi_protocol_supported_tokens({ protocolId: "aave-v4", chainId })` — market underlyings
-4. `get_token_registry` — map symbols (USDC, stETH, WETH) to addresses
+2. `get_defi_protocol_supported_chains` — intersect with `get_chain_registry` (node must have `rpcGateway` per chain)
+3. `get_defi_protocol_supported_tokens({ protocolId: "aave-v4", chainId })` — listed underlyings + `nativeWrapped`
+4. `get_token_registry` — map symbols (USDC, WETH, stETH) to addresses
 
 ## Tool selection
 
 | User intent | MCP tool |
 |-------------|----------|
-| Supply / deposit asset | `ctm_aave_v4_build_deposit_multisign` |
-| Withdraw supplied asset | `ctm_aave_v4_build_withdraw_multisign` |
+| Supply / deposit (lend) | `ctm_aave_v4_build_deposit_multisign` |
+| Withdraw supplied balance | `ctm_aave_v4_build_withdraw_multisign` |
 | Borrow against collateral | `ctm_aave_v4_build_borrow_multisign` |
 | Repay debt | `ctm_aave_v4_build_repay_multisign` |
 
-Example: **borrow USDC against stETH** → deposit/wrap collateral first if needed, then `ctm_aave_v4_build_borrow_multisign` with `underlying` = USDC address, `marketId` from Aave UI/API.
+## Common inputs (all four tools)
 
-## Required inputs (per action)
+| Field | Required | Notes |
+|-------|----------|-------|
+| `keyGenId` | yes | Preferred KeyGen from the node |
+| `chainId` | yes | EVM chain id; RPC/gas from chain registry |
+| `purposeText` | yes | Human-readable reason for the sign request |
+| `underlying` | yes | Token address for the action (see per-action below) |
+| `amountHuman` | yes | Human amount (e.g. `"0.5"`, `"100"`) |
+| `marketId` | no | `main` (default), `core`, or `bluechip` |
+| `useCustomGas` | no | `true` to use chain registry gas config |
+| `spoke` | no | **Omit** — server resolves from Aave API |
 
-- `keyGenId`, `chainId`, `purposeText`
-- `spoke`, `underlying`, `amountHuman`, `marketId` (hub/market segment)
+## Per-action: what `underlying` means
 
-## After submit (`{ requestId }`)
+### Deposit (supply / lend)
+
+- **ERC-20:** pass the token address (e.g. USDC).
+- **Native ETH:** pass `0x0000000000000000000000000000000000000000`, or set `isNativeIn: true` when `underlying` is the chain’s wrapped native (WETH on Ethereum).
+- Optional: `enableAsCollateralAfterSupply: true` to enable the new supply as borrow collateral in the same batch.
+- Flow: may wrap native → approve spoke → `spoke.supply` → optional `setUsingAsCollateral`.
+
+### Withdraw
+
+- `underlying` = asset to withdraw (same address you supplied).
+- Server runs a **health-factor preview** when the user has borrow debt on that spoke. Risky withdrawals are blocked or require `acknowledgeHealthRisk: true`.
+
+### Borrow
+
+- `underlying` = **debt asset** to borrow (e.g. USDC), not collateral.
+- User must already have **collateral supplied** on the same chain (deposit first if needed).
+- Optional: `collateralUnderlying` — collateral token address (e.g. stETH). Helps pick the correct hub when the same debt exists on multiple hubs.
+- Server runs a **health-factor preview** before submit. Dangerous borrows are blocked; borderline cases need `acknowledgeHealthRisk: true`.
+
+### Repay
+
+- `underlying` = debt token being repaid (e.g. USDC).
+- May batch ERC-20 `approve` + `spoke.repay` when allowance is insufficient.
+
+## Basic workflows (teach users)
+
+### Lend only (supply)
+
+1. Confirm chain in registry and Aave-supported.
+2. Resolve token address (registry or `get_defi_protocol_supported_tokens`).
+3. `ctm_aave_v4_build_deposit_multisign` with `underlying`, `amountHuman`, `marketId` (default `main`).
+4. Complete sign lifecycle → `{ requestId }`.
 
-Use base MCP lifecycle:
+### Borrow against collateral
+
+1. **Deposit collateral** if none: e.g. supply stETH or WETH via deposit tool.
+2. **Borrow debt asset:** `ctm_aave_v4_build_borrow_multisign` with `underlying` = debt token (USDC), `amountHuman`, optional `collateralUnderlying` = collateral address.
+3. Explain: health factor must stay above liquidation thresholds; server may refuse or ask for risk acknowledgment.
+
+### Repay and withdraw
+
+1. **Repay:** reduce debt with repay tool (`underlying` = debt token).
+2. **Withdraw:** pull supplied collateral after debt is manageable; watch health-factor gates on withdraw.
+
+## Health factor preflight
+
+For **withdraw**, **borrow**, and **repay**, the server calls the Aave v4 preview API before building the transaction:
+
+| Outcome | Behavior |
+|---------|----------|
+| Allow | Proceeds to build multisign |
+| Block | Returns error (e.g. HF would fall below 1.0) — do not retry with same params |
+| Confirm | Returns error unless `acknowledgeHealthRisk: true` — tell the user the risk and get explicit consent |
+
+Set `skipHealthPreview: true` only when the user explicitly accepts skipping simulation (not recommended).
+
+## After submit (`{ requestId }`)
 
 1. `wait_for_sign_request_ready` (if needed)
 2. `sign_request_agree` (multi-agree)
 3. `trigger_sign_result`
 4. `broadcast_sign_result`
 
+## Example: deposit 0.001 ETH on Ethereum
+
+```json
+{
+  "keyGenId": "<keygen-id>",
+  "chainId": 1,
+  "purposeText": "Supply 0.001 ETH to Aave v4",
+  "useCustomGas": true,
+  "underlying": "0x0000000000000000000000000000000000000000",
+  "marketId": "main",
+  "amountHuman": "0.001"
+}
+```
+
+## Example: borrow USDC against stETH collateral
+
+After stETH is supplied:
+
+```json
+{
+  "keyGenId": "<keygen-id>",
+  "chainId": 1,
+  "purposeText": "Borrow 100 USDC against stETH collateral",
+  "underlying": "<USDC address>",
+  "collateralUnderlying": "<stETH address>",
+  "marketId": "main",
+  "amountHuman": "100"
+}
+```
+
 ## Notes
 
-- Native ETH supply uses wrapped native from Aave API on that chain.
-- Token filter: `api_underlyings` — only listed underlyings are valid per chain.
+- Native supply uses wrapped native from `get_defi_protocol_supported_tokens` (`nativeWrapped`).
+- Token filter: `api_underlyings` — only API-listed underlyings are valid per chain.
+- Merkl rewards and advanced position actions are available in the node app UI, not as separate MCP tools today.

package/dist/agent/skills/curve-dao/SKILL.md

@@ -1,13 +1,132 @@
 ---
 name: curve-dao
-description: Curve Router NG swaps via @curvefi/api session and multisign batch.
+description: Curve Router NG swaps via pool-graph routing and Continuum MPC multisign.
 ---
 
 # Curve DAO (MCP)
 
-1. Confirm chain via `get_defi_protocol_supported_chains` and `isCurveApiChainSupported`.
-2. `get_defi_protocol_supported_tokens` with `rpcUrl` from chain registry loads pool-graph swappable tokens.
-3. `ctm_curve_dao_quote` — `chainId`, `tokenIn`, `tokenOut`, `amountHuman` (optional `tokenInDecimals`). Server resolves `rpcUrl` from chain registry.
-4. `ctm_curve_dao_build_swap_multisign` — `keyGenId`, `chainId`, `purposeText`, `tokenIn`, `tokenOut`, `amountHuman`, `slippagePercent`.
+Curve swaps on Continuum use **Curve Router NG** (`@curvefi/api`): the SDK loads the on-chain **pool graph** for your chain, finds a route between two tokens, then builds an optional **ERC-20 approve** + **`exchange`** batch for the MPC wallet.
 
-Base MCP lifecycle after `{ requestId }`.
+## Architecture (explain this to users)
+
+| Concept | What it is | Agent needs to know |
+|---------|------------|---------------------|
+| **Pool graph** | Curve pools and swappable coins on a chain | Loaded from JSON-RPC via `get_defi_protocol_supported_tokens` (needs `rpcGateway`) |
+| **Router NG** | On-chain contract that executes multi-hop swaps | Calldata from `populateSwap`; server does not need the router address upfront |
+| **Native placeholder** | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` | Curve’s id for native ETH (and chain native) in routes — **not** the WETH contract |
+| **Wrapped native** | WETH / WMATIC etc. | For **quotes**, WETH is treated as `0xeeee` in routing. For **build**, pass the **wrapped native contract address** as `tokenIn` when selling native ETH |
+
+There is no separate “hub” or “spoke” — routing is entirely determined by Curve’s pool connectivity on that chain.
+
+## Before any swap
+
+1. `load_defi_protocol({ protocolId: "curve-dao" })`
+2. `get_defi_protocol_supported_chains` — must intersect with `get_chain_registry` (node needs `rpcGateway`)
+3. `get_defi_protocol_supported_tokens({ protocolId: "curve-dao", chainId })` — tokens reachable in Curve’s pool graph on that RPC
+4. `get_token_registry` — map user symbols (USDC, crvUSD, ETH) to addresses
+
+If token discovery returns empty, configure `rpcGateway` for the chain first, then retry.
+
+## Tool flow (two steps → one sign request)
+
+| Step | Tool | Creates sign request? |
+|------|------|------------------------|
+| 1. Quote | `ctm_curve_dao_quote` | No — returns route + expected output |
+| 2. Execute | `ctm_curve_dao_build_swap_multisign` | Yes → `{ requestId }` |
+
+Always quote first unless the user already has a verified route. Explain quote output (`output`, `route`, `priceImpactPercent`) before submitting.
+
+## `ctm_curve_dao_quote`
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `chainId` | yes | Must be Curve-supported (see supported chains below) |
+| `tokenIn` | yes | ERC-20 address, or native: `0xeeee…`, `0x0`, `eth` |
+| `tokenOut` | yes | ERC-20 address or `0xeeee…` for native out |
+| `amountHuman` | yes | Human decimal string of **tokenIn** (e.g. `"100"`, `"0.5"`) |
+| `tokenInDecimals` | no | Omit to read decimals on-chain (native = 18) |
+| `rpcUrl` | no | **Do not pass** — server injects from chain registry |
+
+**Quote output (typical):** `inputAmount`, `output`, `route`, `priceImpactPercent`, `tokenInRouterId`, `tokenOutRouterId`.
+
+## `ctm_curve_dao_build_swap_multisign`
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `keyGenId` | yes | MPC KeyGen |
+| `chainId` | yes | Same chain as quote |
+| `purposeText` | yes | Human-readable purpose |
+| `tokenIn` | yes | **ERC-20 address** sold. Native ETH in: use **wrapped native** address (e.g. WETH on Ethereum), not `0xeeee` |
+| `tokenOut` | yes | Output token address or `0xeeee…` for native |
+| `amountHuman` | yes | Same human amount as quote (tokenIn units) |
+| `slippagePercent` | yes | Number strictly between 0 and 100 (e.g. `0.5` for 0.5%) |
+| `useCustomGas` | no | `true` for chain registry gas settings |
+
+Server resolves `keyGen`, `executorAddress`, `rpcUrl`, `chainDetail` from `keyGenId` + registry.
+
+**Transaction batch:** optional `approve` to Curve router when allowance is low, then `CurveRouterNG.exchange` (native-in may be 1 tx without approve).
+
+## Native ETH swaps
+
+| Phase | tokenIn |
+|-------|---------|
+| Quote | `0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee` or `0x0` |
+| Build | Wrapped native from `get_defi_protocol_supported_tokens` / chain (e.g. WETH `0xC02…` on Ethereum) |
+
+Tell users: quoting uses Curve’s native placeholder; the MPC builder maps wrapped native → native route automatically.
+
+## Supported chains (indicative)
+
+Use `get_defi_protocol_supported_chains` as source of truth. Curve SDK commonly supports:
+
+Ethereum (1), Optimism (10), BSC (56), Gnosis (100), Polygon (137), Sonic (146), Unichain (196), Fantom (250), Fraxtal (252), zkSync (324), HyperEVM (999), Moonbeam (1284), Kava (2222), Mantle (5000), Base (8453), Arbitrum (42161), Celo (42220), Avalanche (43114), Aurora (1313161554).
+
+## Example: swap 100 USDC → ETH on Ethereum
+
+**1. Quote**
+
+```json
+{
+  "chainId": 1,
+  "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "tokenOut": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+  "amountHuman": "100"
+}
+```
+
+**2. Build** (after user confirms quote output)
+
+```json
+{
+  "keyGenId": "<keygen-id>",
+  "chainId": 1,
+  "purposeText": "Swap 100 USDC to ETH via Curve",
+  "useCustomGas": true,
+  "tokenIn": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "tokenOut": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+  "amountHuman": "100",
+  "slippagePercent": 0.5
+}
+```
+
+## After submit (`{ requestId }`)
+
+1. `wait_for_sign_request_ready` (if needed)
+2. `sign_request_agree` (multi-agree)
+3. `trigger_sign_result`
+4. `broadcast_sign_result`
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---------|----------------|
+| Empty route / zero output | Pair not connected in pool graph, or amount precision too high for token decimals |
+| Chain not supported | `chainId` missing from Curve SDK networks |
+| No rpcGateway | Chain not in node registry or missing RPC URL |
+| Quote works, build fails | `tokenIn`/`tokenOut`/`amountHuman`/`slippagePercent` differ from quote; native build used `0xeeee` instead of wrapped native for `tokenIn` |
+
+## Notes
+
+- Curve discovers tokens from the **pool graph**, not an allowlist — `get_defi_protocol_supported_tokens` lists what is swappable on your RPC.
+- Slippage applies to the router `populateSwap` call; explain it to users before building.
+- There is no Curve MCP “preview health factor” — swaps are not lending actions.

package/dist/agent/skills/uniswap-v4/SKILL.md

@@ -1,22 +1,198 @@
 ---
 name: uniswap-v4
-description: Uniswap V4 swaps via Trade API quote, swap calldata, and multisign submit.
+description: Uniswap v4 Universal Router swaps via Trade API quote, calldata, and MPC multisign.
 ---
 
 # Uniswap v4 (MCP)
 
-## Multi-step swap flow
+Uniswap swaps on Continuum use the **Uniswap Trade API** (quote + swap calldata) and the on-chain **Universal Router**. The MCP path uses **classic ERC-20 approve** (Permit2 disabled), matching the node app — not Permit2 signatures.
 
-1. `ctm_uniswap_v4_quote` — requires `UNISWAP_API_KEY` env on MCP server
-2. `ctm_uniswap_v4_create_swap` — Universal Router calldata
-3. `ctm_uniswap_v4_build_swap_multisign` — submits sign request → `{ requestId }`
+## Architecture (explain this to users)
 
-## Chains / tokens
+| Concept | What it is | Agent needs to know |
+|---------|------------|---------------------|
+| **Trade API** | Uniswap-hosted routing/quote service | Requires `UNISWAP_API_KEY` on the node (not in tool input) |
+| **Universal Router** | On-chain entry contract per chain | Address is embedded in Trade API `swap` calldata — do not guess |
+| **Swapper** | Address that executes the swap | MPC wallet = KeyGen `ethereumaddress`; pass `keyGenId` and server resolves `swapper` |
+| **Permit2** | Optional allowance path | **Disabled** in MCP (`permit2Disabled: true`) — uses direct ERC-20 approve batch instead |
 
-- Chains: `get_defi_protocol_supported_chains` (Universal Router map)
-- Tokens: any ERC-20 on supported chain; use `get_token_registry` for wallet tokens
-- `tokenOut` may be any address on same chain
+Unlike Aave, there are no hubs/spokes — routing is entirely inside the Trade API response.
 
-## After submit
+## Before any swap
 
-Base MCP: `trigger_sign_result` → `broadcast_sign_result`.
+1. `load_defi_protocol({ protocolId: "uniswap-v4" })`
+2. Confirm `UNISWAP_API_KEY` is set: `list_environment_variables` or `load_defi_protocol` response (`uniswapApiKeyConfigured`). Create a key at [Uniswap developer dashboard](https://developers.uniswap.org/dashboard/welcome) and add it in **Node → AI Agent → Variables**.
+3. `get_defi_protocol_supported_chains` — Universal Router must exist on `chainId`
+4. `get_token_registry` — resolve `tokenIn` / `tokenOut` addresses (any ERC-20 on supported chains)
+
+## Tool flow (three steps → one sign request)
+
+| Step | Tool | Creates sign request? |
+|------|------|------------------------|
+| 1. Quote | `ctm_uniswap_v4_quote` | No — routing + amounts |
+| 2. Calldata | `ctm_uniswap_v4_create_swap` | No — Universal Router tx skeleton |
+| 3. Submit | `ctm_uniswap_v4_build_swap_multisign` | Yes → `{ requestId }` |
+
+Do not skip steps. Pass the **full quote JSON** into `create_swap`, then pass **both** `create_swap` output and quote snapshot into `build_swap_multisign`.
+
+## `ctm_uniswap_v4_quote`
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `type` | yes | `EXACT_INPUT` (sell exact tokenIn) or `EXACT_OUTPUT` (receive exact tokenOut) |
+| `amount` | yes | **Base units** string (wei for 18-decimal tokens). For human amounts, convert with token decimals first |
+| `tokenIn` | yes | Input token; native ETH: `0x0000000000000000000000000000000000000000` |
+| `tokenOut` | yes | Output token address (same chain) |
+| `chainId` | yes | Must be Uniswap-supported |
+| `keyGenId` | recommended | Server resolves `swapper` (MPC executor) |
+| `swapper` | optional | MPC wallet address if `keyGenId` omitted |
+| `slippage` | no | Defaults to **0.5** (percent) when Permit2 disabled |
+| `permit2Disabled` | no | Defaults **true** (classic approve path) |
+| `uniswapApiKey` | no | **Do not pass** — injected from `UNISWAP_API_KEY` Variable |
+
+**Tip:** For `EXACT_INPUT` with human amounts, read token decimals on-chain (or registry) and convert to wei before quoting.
+
+## `ctm_uniswap_v4_create_swap`
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `fullQuoteFromPermit` | yes | **Entire** JSON object returned by `ctm_uniswap_v4_quote` |
+| `swapTransactionDeadlineUnix` | no | On-chain deadline; default ~30 minutes from now |
+| `uniswapApiKey` | no | Injected by server |
+
+**Output:** `{ swap: { to, data, value, gasLimit? }, requestId?, gasFee? }` — keep the full object for the next step.
+
+## `ctm_uniswap_v4_build_swap_multisign`
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| `keyGenId` | yes | MPC KeyGen |
+| `chainId` | yes | Same as quote |
+| `purposeText` | yes | Human-readable purpose |
+| `tokenIn` | yes | Same as quote (`0x0` for native ETH in) |
+| `swap` | yes | `swap` object from `create_swap` response |
+| `createSwapResponse` | yes | Full `create_swap` JSON |
+| `fullQuoteSnapshot` | yes | Full quote JSON from step 1 |
+| `swapDeadlineUnix` | yes | **Same** deadline passed to `create_swap` |
+| `slippagePercent` | no | Extra approve headroom for `EXACT_OUTPUT` swaps |
+| `useCustomGas` | no | `true` for chain registry gas |
+
+Server resolves `keyGen`, `executorAddress`, `rpcUrl`, `chainDetail`.
+
+**Transaction batch:** 1–3 txs — optional ERC-20 approve(s), then Universal Router `swap` (native-in may skip approve).
+
+## Supported chains
+
+Use `get_defi_protocol_supported_chains` as source of truth. Universal Router is deployed on major EVM chains including:
+
+Ethereum (1), Sepolia (11155111), Polygon (137), Optimism (10), Arbitrum (42161), Base (8453), BSC (56), Avalanche (43114), Celo (42220), zkSync (324), Blast (81457), and others in the router map.
+
+**Tokens:** Any ERC-20 on a supported chain; `tokenOut` can be any valid address with liquidity.
+
+## Example: EXACT_INPUT — sell 0.1 ETH for USDC on Ethereum
+
+Assume 0.1 ETH = `100000000000000000` wei.
+
+**1. Quote**
+
+```json
+{
+  "type": "EXACT_INPUT",
+  "amount": "100000000000000000",
+  "tokenIn": "0x0000000000000000000000000000000000000000",
+  "tokenOut": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
+  "chainId": 1,
+  "keyGenId": "<keygen-id>"
+}
+```
+
+**2. Create swap**
+
+```json
+{
+  "fullQuoteFromPermit": "<full quote JSON from step 1>"
+}
+```
+
+**3. Build multisign**
+
+```json
+{
+  "keyGenId": "<keygen-id>",
+  "chainId": 1,
+  "purposeText": "Swap 0.1 ETH to USDC via Uniswap v4",
+  "useCustomGas": true,
+  "tokenIn": "0x0000000000000000000000000000000000000000",
+  "swap": "<swap object from create_swap>",
+  "createSwapResponse": "<full create_swap JSON>",
+  "fullQuoteSnapshot": "<full quote JSON from step 1>",
+  "swapDeadlineUnix": 1735689600
+}
+```
+
+Use the same `swapTransactionDeadlineUnix` in step 2 and `swapDeadlineUnix` in step 3.
+
+## Teaching users about slippage
+
+- **Quote slippage** (`slippage` on quote, default 0.5%): Trade API routing tolerance.
+- **On-chain batch** may add approve headroom; for `EXACT_OUTPUT`, optional `slippagePercent` on build adjusts approval sizing.
+- Explain expected input/output from quote JSON before submitting the sign request.
+
+## After submit (`{ requestId }`)
+
+1. `wait_for_sign_request_ready` (if needed)
+2. `sign_request_agree` (multi-agree)
+3. `trigger_sign_result`
+4. `broadcast_sign_result`
+
+## Troubleshooting
+
+| Symptom | Likely cause |
+|---------|----------------|
+| Missing API key error | `UNISWAP_API_KEY` not in node Variables |
+| Quote fails | Unsupported chain, illiquid pair, or `amount` not in base units |
+| Build fails after quote | Quote/swap/deadline mismatch between steps; stale quote (re-quote) |
+| Wrong swapper | Missing or wrong `keyGenId`; swapper must be MPC executor |
+
+## Liquidity provision (V4 positions)
+
+Uniswap V4 LP uses the **Liquidity Provisioning API** (`POST /lp/create`, `/increase`, `/decrease`, `/claim`) and on-chain **Position Manager** NFTs. There is **no separate LP-token staking** — fees accrue in-position; collect via `/lp/claim`.
+
+MCP uses **classic ERC-20 approve** batches (Permit2 disabled), matching swaps.
+
+### LP tool flows
+
+| Action | Prep tool | Build multisign |
+|--------|-----------|-----------------|
+| Mint new position | `ctm_uniswap_v4_lp_create_position` | `ctm_uniswap_v4_build_mint_liquidity_multisign` |
+| Increase | `ctm_uniswap_v4_lp_increase` | `ctm_uniswap_v4_build_increase_liquidity_multisign` |
+| Decrease | `ctm_uniswap_v4_lp_decrease` | `ctm_uniswap_v4_build_decrease_liquidity_multisign` |
+| Collect fees | `ctm_uniswap_v4_lp_collect` | `ctm_uniswap_v4_build_collect_fees_multisign` |
+| List positions | `ctm_uniswap_v4_lp_list_positions` | — (token registry ERC721) |
+| Register position NFT | `ctm_uniswap_v4_register_position_nft` | — (management-signed) |
+| Register from mint tx | `ctm_uniswap_v4_register_position_from_mint_tx` | — (after mint execute) |
+
+### Mint workflow
+
+1. Resolve pool (`existingPool` with `poolReference` = V4 pool id, or `newPool` to initialize).
+2. Set price range via `priceBounds` (human prices) or `tickBounds`.
+3. `independentToken`: one token + amount in base units; API computes the other.
+4. `ctm_uniswap_v4_lp_create_position` → full JSON with `create` tx + `token0`/`token1` amounts.
+5. `ctm_uniswap_v4_build_mint_liquidity_multisign` with `lpResponse` = full create JSON, `purposeText`, `keyGenId`, `chainId`.
+6. Pass `nativeWrapped` when pool uses native ETH (`0x0`) as token0 or token1.
+7. After execute: `ctm_uniswap_v4_register_position_from_mint_tx` with the mint step `txHash` — adds the position ERC721 to the node token registry so `lp_list_positions` can find it.
+
+### Manage existing positions (MCP — token registry, no block scan)
+
+Agents **do not** scan blockchain logs for positions. Positions must appear as **ERC721** entries in the node token registry (Uniswap V4 Position Manager contract + `tokenId`).
+
+1. `ctm_uniswap_v4_lp_list_positions` with `keyGenId` + `chainId` (or `walletAddress` + `chainId`).
+2. If a position is missing: `ctm_uniswap_v4_register_position_nft` (known `tokenId`), `add_to_token_registry` (ERC721), or in the Continuum app use **Add Token** or **Manage liquidity → Refresh positions** (blockchain scan).
+3. For increase/decrease/collect, pass `nftTokenId` / `tokenId` from the list output plus `token0Address`/`token1Address` from position context. Prep tools error with registry hints when the NFT is not saved.
+4. Decrease uses `liquidityPercentageToDecrease` (1–100).
+
+## Notes
+
+- Do **not** pass `uniswapApiKey` in tool calls — the MCP server injects it.
+- Native ETH always uses `tokenIn: 0x0` for Uniswap (not `0xeeee` — that is Curve’s placeholder).
+- `get_defi_protocol_skill` (this file) is the canonical workflow reference for agents.