pragma-openclaw 0.1.2 → 0.1.3

package/agents/kairos/AGENTS.md

@@ -12,6 +12,7 @@
 6. **Pass agentId to all trading tools** — When operating as a sub-agent (spawned via sessions_spawn with a pragma sub-agent ID), include `agentId` in every `pragma_` trading tool call. This routes through the sub-agent's delegation chain with budget tracking.
 7. **Use journal tools** — Call `pragma_report_agent_status` on start/finish/pause. Call `pragma_write_agent_memo` to persist reasoning (baselines, watchlists, trade plans) that survives context compaction.
 8. **NEVER delegate** — Call ALL tools directly. Never spawn sub-agents or sub-tasks. You ARE the analyst and executor. Delegating loses your accumulated context.
+9. **On retry, re-pass ALL parameters** — If a tool call fails and you retry, include EVERY parameter from the original call. Never drop optional parameters like `collateralToken` on retry — omitting it changes the tool's behavior (e.g., defaulting to MON collateral instead of LVUSD).
 
 ---
 
@@ -33,6 +34,19 @@
 | `pragma.leverup_open_limit_order` | Place limit order |
 | `pragma.leverup_cancel_limit_order` | Cancel limit order |
 
+### Collateral Tokens
+
+All `pragma.leverup_open_trade` and `pragma.leverup_open_limit_order` calls require `collateralToken`:
+
+| Token | Decimals | Notes |
+|-------|----------|-------|
+| **MON** | 18 | Native — full amount sent as msg.value. Default if omitted. |
+| **USDC** | 6 | Stablecoin |
+| **LVUSD** | 18 | LeverUp vault USD |
+| **LVMON** | 18 | LeverUp vault MON |
+
+**ALWAYS specify `collateralToken` explicitly.** Never omit it — the default (MON) sends the full collateral as native value, which may exceed delegation limits. On retry, re-pass the same `collateralToken` value.
+
 ### Market Intelligence (8)
 | Tool | Purpose | x402 Cost |
 |------|---------|-----------|

package/agents/pragma/AGENTS.md

@@ -13,6 +13,7 @@
 7. **Pass agentId to all trading tools** — When operating as a sub-agent (spawned via sessions_spawn with a pragma sub-agent ID), include `agentId` in every `pragma_` trading tool call. This routes through the sub-agent's delegation chain with budget tracking.
 8. **Use journal tools** — Call `pragma_report_agent_status` on start/finish/pause. Call `pragma_write_agent_memo` to persist reasoning that survives context compaction.
 9. **NEVER delegate** — Call ALL tools directly. Never spawn sub-agents or sub-tasks. You ARE the executor. Delegating loses your accumulated context.
+10. **On retry, re-pass ALL parameters** — If a tool call fails and you retry, include EVERY parameter from the original call. Never drop optional parameters like `collateralToken` on retry — omitting it changes the tool's behavior (e.g., defaulting to MON collateral instead of LVUSD).
 
 ---
 
@@ -34,6 +35,19 @@
 | `pragma.leverup_open_limit_order` | Place limit order |
 | `pragma.leverup_cancel_limit_order` | Cancel limit order |
 
+### Collateral Tokens
+
+All `pragma.leverup_open_trade` and `pragma.leverup_open_limit_order` calls require `collateralToken`:
+
+| Token | Decimals | Notes |
+|-------|----------|-------|
+| **MON** | 18 | Native — full amount sent as msg.value. Default if omitted. |
+| **USDC** | 6 | Stablecoin |
+| **LVUSD** | 18 | LeverUp vault USD |
+| **LVMON** | 18 | LeverUp vault MON |
+
+**ALWAYS specify `collateralToken` explicitly.** Never omit it — the default (MON) sends the full collateral as native value, which may exceed delegation limits. On retry, re-pass the same `collateralToken` value.
+
 ### nad.fun (8)
 | Tool | Purpose |
 |------|---------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pragma-openclaw",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "pragma plugin for OpenClaw — on-chain trading and market intelligence on monad",
   "type": "module",
   "main": "dist/index.js",

package/skills/pragma-core/SKILL.md

@@ -85,6 +85,8 @@ metadata:
 
 6. **Use the correct delegation tool.** When you need a new delegation, use `pragma_request_delegation` (the web-based approval flow). NEVER use `pragma_create_root_delegation` — that tool requires macOS Touch ID and will always fail on this platform.
 
+7. **On retry, re-pass ALL parameters.** If a tool call fails and you retry, include EVERY parameter from the original call. Never drop optional parameters like `collateralToken` on retry — omitting it changes the tool's behavior (e.g., defaulting to MON collateral instead of LVUSD).
+
 ---
 
 ## Prerequisites
@@ -110,8 +112,45 @@ You do NOT need to check delegation before every operation — just try the oper
 | "No delegation found" | Tell user → use pragma-delegation skill to create one |
 | "LimitedCalls exceeded" | Delegation used up all allowed calls → renew |
 
-**Session key gas management:**
-- **Low gas (> 0.02 MON remaining):** Use `pragma_fund_session_key` — it transfers MON from the user's Smart Account to the session key via delegation. No extra approval needed.
+---
+
+## Session Key Gas Management
+
+**MANDATORY: Check session key balance before ANY write operation.**
+
+### Pre-Transaction Check
+
+Before every swap, transfer, wrap, unwrap, buy, sell, or open/close trade:
+
+```
+1. pragma_check_session_key_balance (with operationType or estimatedOperations)
+2. If needsFunding: pragma_fund_session_key → WAIT for result
+3. THEN execute the operation
+```
+
+### Gas Cost Reference
+
+| Operation | Gas Cost (MON) |
+|-----------|---------------|
+| swap | 0.14 |
+| transfer | 0.04 |
+| wrap / unwrap | 0.04 |
+| leverup open / close | 0.14 |
+| nadfun buy / sell | 0.14 |
+
+**Formula:** `total_gas = sum(operation_costs) + 0.02 MON buffer`
+
+**Example:** Swap + transfer = 0.14 + 0.04 + 0.02 buffer = **0.20 MON needed**
+
+### Funding Rule
+
+**NEVER call `pragma_fund_session_key` and execution tools simultaneously.**
+
+The session key needs funds BEFORE it can pay gas. Always fund first, wait for completion, then execute.
+
+### Gas Thresholds
+
+- **Low gas (> 0.02 MON remaining):** Use `pragma_fund_session_key` — transfers MON from Smart Account via delegation. No extra approval needed.
 - **Zero gas (< 0.02 MON):** Self-funding CANNOT work because the session key needs gas to submit the funding transaction. Tell the user: "Your session key is out of gas. Please send at least 0.5 MON to: [session key address]"
 - **No UserOp on this platform.** The bundler/UserOp path is not available here. Do NOT mention UserOp to the user.
 
@@ -173,7 +212,7 @@ You do NOT need to check delegation before every operation — just try the oper
 | `pragma_leverup_get_quote` | Position quote (margin, fees, liq price) |
 | `pragma_leverup_open_trade` | Open market position |
 | `pragma_leverup_close_trade` | Close position |
-| `pragma_leverup_update_margin` | Add/remove margin |
+| `pragma_leverup_update_margin` | Add margin (normal leverage only) |
 | `pragma_leverup_update_tpsl` | Update TP/SL levels |
 | `pragma_leverup_get_market_stats` | OI, volume, spread per pair |
 | `pragma_leverup_get_funding_rates` | Holding fee rates (carry cost) |
@@ -224,43 +263,164 @@ You do NOT need to check delegation before every operation — just try the oper
 
 ---
 
+## LeverUp Platform Constraints
+
+**CRITICAL: Always perform a risk simulation (`pragma_leverup_get_quote`) before opening any position.**
+
+### Two Trading Modes
+
+| Feature | Normal Mode (1-100x) | Zero-Fee Mode (500x/750x/1001x) |
+|---------|----------------------|----------------------------------|
+| **Pairs** | All standard pairs (BTC, ETH, MON, etc.) | 500BTC/USD, 500ETH/USD only |
+| **Open/Close Fees** | 0.045% | 0% if PnL < 0, profit sharing if profitable |
+| **Order Types** | Market + Limit | **Market only** |
+| **Add/Remove Margin** | Yes | **Not allowed** |
+| **Leverage Values** | Any from 1-100 | **Exactly 500, 750, or 1001** |
+
+**CRITICAL:** If user requests 500BTC or 500ETH, they MUST use exactly 500x, 750x, or 1001x leverage. Any other value will fail with "Below degen mode min leverage" error.
+
+### Order Types: Market vs Limit
+
+| Order Type | When to Use | Trigger Behavior |
+|------------|-------------|------------------|
+| **Market** (`pragma_leverup_open_trade`) | Execute immediately at current price | Fills instantly |
+| **Limit** (`pragma_leverup_open_limit_order`) | Wait for better entry price | Triggers when market reaches price |
+
+**Limit Order Trigger Rules:**
+- **Long limit orders:** Trigger price must be BELOW current market (buy the dip)
+- **Short limit orders:** Trigger price must be ABOVE current market (sell the top)
+
+**Limit orders are NOT available for Zero-Fee pairs (500BTC/500ETH).**
+
+### Minimum Trade Thresholds
+
+LeverUp enforces the following limits. Always inform the user if their trade is near or below these thresholds.
+
+- **HARD LIMIT — Minimum Position Size**: $200.00 USD (Margin x Leverage) — **Contract will reject trades below this**
+- **Soft Guideline — Minimum Margin**: $10.00 USD (recommended but not strictly enforced)
+
+### Collateral Options
+
+**CRITICAL: Always pass the `collateralToken` parameter explicitly when opening LeverUp trades. Never omit it — the default (MON) may not be what the user intends.**
+
+| Token | Decimals | When to Use |
+|-------|----------|-------------|
+| **MON** (native) | 18 | Default — full amount sent as native value |
+| **USDC** | 6 | Stablecoin strategies |
+| **LVUSD** | 18 | LeverUp vault USD token |
+| **LVMON** | 18 | LeverUp vault MON token |
+
+**On retry after failure:** You MUST re-pass `collateralToken` with the same value. Dropping it changes behavior (defaults to MON, which sends full amount as native value and may hit delegation limits).
+
+### Stop Loss (SL) and Take Profit (TP)
+
+SL and TP can be set when opening a position. Both are optional (set to 0 to disable).
+
+**TP Limits (Contract-Enforced):**
+
+| Leverage | Max Take Profit |
+|----------|-----------------|
+| < 50x | 500% profit |
+| >= 50x | 300% profit |
+
+**SL/TP Rules:**
+
+- Stop Loss: Must be BELOW entry price (Long) or ABOVE entry price (Short)
+- Take Profit: Must be ABOVE entry price (Long) or BELOW entry price (Short)
+- **Cannot be cancelled** once set, but can be edited via `pragma_leverup_update_tpsl`
+- Prices are in USD (e.g., "85000" for $85,000)
+
+**Example — Long BTC at $90,000:**
+- Valid SL: $85,000 (below entry)
+- Valid TP: $100,000 (above entry, within 500%/300% limit)
+
+**Example — Short BTC at $90,000:**
+- Valid SL: $95,000 (above entry)
+- Valid TP: $80,000 (below entry)
+
+### Managing Positions
+
+1. `pragma_leverup_list_positions` — Check Health Factor of active trades.
+2. If Health < 20%: Suggest `pragma_leverup_update_margin` to add collateral.
+   - **NOTE:** This does NOT work for 500x/750x/1001x positions!
+3. To update TP/SL: Use `pragma_leverup_update_tpsl`.
+4. To lock in profit: Use `pragma_leverup_close_trade`.
+
+### Update Margin Limitations
+
+`pragma_leverup_update_margin` only works for normal leverage (1-100x) positions.
+
+- **Only ADDING margin is supported** — the contract does not allow margin withdrawal.
+- **Zero-Fee positions (500x/750x/1001x) CANNOT add margin.**
+- The tool will show a warning, and the contract will reject the transaction if attempted.
+
+### Update TP/SL
+
+Use `pragma_leverup_update_tpsl` to modify take profit and stop loss on existing positions:
+
+- Pass price in USD (e.g., '110000' for $110,000)
+- Set to '0' to disable TP or SL
+- At least one of `takeProfit` or `stopLoss` must be provided
+- Works for all position types including Zero-Fee positions
+
+### Managing Limit Orders
+
+1. `pragma_leverup_list_limit_orders` — View all pending orders (not yet filled)
+2. `pragma_leverup_cancel_limit_order` — Cancel one or more pending orders
+   - Accepts single orderHash or array for batch cancel
+   - Use batch cancel when user wants to "cancel all orders"
+
+**Distinction:**
+- `pragma_leverup_list_positions` → FILLED positions (active trades)
+- `pragma_leverup_list_limit_orders` → PENDING orders (waiting to trigger)
+
+---
+
 ## Operation Flows
 
 ### Swap (Single)
 
 ```
 1. pragma_get_all_balances             → Verify source token balance
-2. pragma_get_swap_quote(from, to, amount) → Show quote to user
-3. pragma_execute_swap(from, to, amount)   → Execute after confirmation
-4. pragma_get_all_balances             → Confirm new balances
+2. pragma_check_session_key_balance    → Verify gas (operationType: "swap")
+3. If needsFunding: pragma_fund_session_key → WAIT
+4. pragma_get_swap_quote(from, to, amount) → Show quote to user
+5. pragma_execute_swap(from, to, amount)   → Execute after confirmation
+6. pragma_get_all_balances             → Confirm new balances
 ```
 
 ### Swap (Batch)
 
-For multiple swaps in sequence:
+For multiple independent swaps:
 
 ```
 1. pragma_get_all_balances             → Portfolio snapshot
-2. For each swap:
+2. pragma_check_session_key_balance    → estimatedOperations: N
+3. If needsFunding: pragma_fund_session_key → WAIT
+4. For each swap:
    a. pragma_get_swap_quote(...)       → Get quote
    b. pragma_execute_swap(...)         → Execute
-3. pragma_get_all_balances             → Final portfolio
+5. pragma_get_all_balances             → Final portfolio
 ```
 
 ### Transfer
 
 ```
 1. pragma_get_balance(token)           → Verify sufficient balance
-2. pragma_transfer(token, to, amount)  → Execute transfer
-3. pragma_get_balance(token)           → Confirm new balance
+2. pragma_check_session_key_balance    → operationType: "transfer"
+3. If needsFunding: pragma_fund_session_key → WAIT
+4. pragma_transfer(token, to, amount)  → Execute transfer
+5. pragma_get_balance(token)           → Confirm new balance
 ```
 
 ### Wrap / Unwrap
 
 ```
 1. pragma_get_all_balances             → Check MON/WMON balance
-2. pragma_wrap(amount) or pragma_unwrap(amount)
-3. pragma_get_all_balances             → Confirm
+2. pragma_check_session_key_balance    → operationType: "wrap" or "unwrap"
+3. If needsFunding: pragma_fund_session_key → WAIT
+4. pragma_wrap(amount) or pragma_unwrap(amount)
+5. pragma_get_all_balances             → Confirm
 ```
 
 ### nad.fun Buy
@@ -270,8 +430,10 @@ For multiple swaps in sequence:
 2. pragma_nadfun_token_info(address)   → Token details
 3. pragma_nadfun_status(address)       → Bonding curve progress
 4. pragma_nadfun_quote(address, "buy", amount) → Price quote
-5. pragma_nadfun_buy(address, amount)  → Execute buy
-6. pragma_nadfun_positions             → Confirm position
+5. pragma_check_session_key_balance    → operationType: "swap"
+6. If needsFunding: pragma_fund_session_key → WAIT
+7. pragma_nadfun_buy(address, amount)  → Execute buy
+8. pragma_nadfun_positions             → Confirm position
 ```
 
 ### nad.fun Sell
@@ -279,37 +441,52 @@ For multiple swaps in sequence:
 ```
 1. pragma_nadfun_positions             → Current holdings
 2. pragma_nadfun_quote(address, "sell", amount) → Price quote
-3. pragma_nadfun_sell(address, amount) → Execute sell
-4. pragma_nadfun_positions             → Confirm
+3. pragma_check_session_key_balance    → operationType: "swap"
+4. If needsFunding: pragma_fund_session_key → WAIT
+5. pragma_nadfun_sell(address, amount) → Execute sell
+6. pragma_nadfun_positions             → Confirm
 ```
 
 ### LeverUp Open Position
 
 ```
-1. pragma_get_all_balances             → Verify LVUSD/collateral balance
+1. pragma_get_all_balances             → Verify collateral balance
 2. pragma_leverup_list_pairs           → Current prices and spreads
-3. pragma_leverup_get_quote(pair, direction, leverage, size) → Quote
-4. pragma_leverup_open_trade(pair, direction, leverage, size, tp, sl)
-5. pragma_leverup_list_positions       → Confirm position opened
+3. pragma_leverup_get_quote(pair, direction, leverage, margin) → MANDATORY quote
+4. Review: Check minimum thresholds, Zero-Fee restrictions, warnings
+5. Confirm with user: Show margin, position size, liq price, collateral token
+6. pragma_check_session_key_balance    → operationType: "swap"
+7. If needsFunding: pragma_fund_session_key → WAIT
+8. pragma_leverup_open_trade(pair, direction, leverage, margin, collateralToken, tp, sl)
+   ↑ ALWAYS pass collateralToken explicitly
+9. pragma_leverup_list_positions       → Confirm position opened
 ```
 
 ### LeverUp Close Position
 
 ```
 1. pragma_leverup_list_positions       → Find position to close
-2. pragma_leverup_close_trade(positionId) → Close
-3. pragma_get_all_balances             → Confirm PnL settled
+2. pragma_check_session_key_balance    → operationType: "swap"
+3. If needsFunding: pragma_fund_session_key → WAIT
+4. pragma_leverup_close_trade(positionId) → Close
+5. pragma_get_all_balances             → Confirm PnL settled
 ```
 
 ### Limit Order
 
 ```
-1. pragma_leverup_list_pairs           → Current prices
-2. pragma_leverup_get_quote(pair, direction, leverage, size) → Quote at target
-3. pragma_leverup_open_limit_order(pair, direction, leverage, size, triggerPrice, tp, sl)
-4. pragma_leverup_list_limit_orders    → Confirm order placed
+1. pragma_leverup_get_market_stats     → Current prices
+2. pragma_leverup_get_quote(pair, direction, leverage, margin) → Quote at target
+3. Confirm trigger price with user (Long: below market, Short: above market)
+4. pragma_check_session_key_balance    → operationType: "swap"
+5. If needsFunding: pragma_fund_session_key → WAIT
+6. pragma_leverup_open_limit_order(pair, direction, leverage, margin, triggerPrice, collateralToken, tp, sl)
+   ↑ ALWAYS pass collateralToken explicitly
+7. pragma_leverup_list_limit_orders    → Confirm order placed
 ```
 
+**Note:** SL/TP for limit orders are validated against the TRIGGER price, not current market.
+
 ---
 
 ## Token Resolution
@@ -323,6 +500,16 @@ The MCP server handles resolution automatically. Use `pragma_list_verified_token
 
 ---
 
+## Relative Amounts
+
+When user says "all", "half", "max", or a percentage:
+
+1. `pragma_get_balance` FIRST to get actual amount
+2. Calculate the relative value
+3. Proceed with the appropriate operation flow
+
+---
+
 ## Error Handling
 
 | Error | Action |
@@ -331,6 +518,10 @@ The MCP server handles resolution automatically. Use `pragma_list_verified_token
 | "Insufficient balance" | Show current balance, suggest amount adjustment |
 | "Slippage exceeded" | Retry with higher slippage or smaller amount |
 | "Delegation expired" | Tell user to approve a new delegation |
+| "LimitedCalls exceeded" | Delegation used up all allowed calls → renew |
+| "ValueLteEnforcer:value-too-high" | Collateral token likely wrong — check `collateralToken` param |
+| "Position is too small" | Margin x Leverage < $200 — increase margin or leverage |
+| "Below degen mode min leverage" | Zero-Fee pairs need exactly 500x, 750x, or 1001x |
 | "Rate limited" | Wait and retry |
 | "Network error" | Retry once, then report |
 
@@ -350,9 +541,39 @@ The MCP server handles resolution automatically. Use `pragma_list_verified_token
 - Expected outcome
 - Any fees or slippage
 
+**Unverified token warning:**
+- If token is NOT in `pragma_list_verified_tokens`, show FULL contract address
+- Include warning: "This token is unverified. Verify this is the correct contract address."
+- This prevents users from swapping to copycat/scam tokens with the same symbol
+
 **Execute without extra confirmation:**
 - Balance checks
 - Quote requests
 - Market data queries
 - Token info lookups
 - Read-only operations
+
+---
+
+## Response Format
+
+**Balances:**
+```
+Token: Amount ($Value)
+```
+
+**Quotes:**
+```
+Swap: 1 TOKEN_A → 0.999 TOKEN_B
+Impact: 0.1%
+Route: Direct
+```
+
+**Results:**
+```
+Success!
+Tx: 0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
+Received: 0.999 TOKEN_B
+```
+
+**IMPORTANT:** Always show FULL transaction hashes (all 66 characters). Never truncate tx hashes — users need to copy them.