pragma-openclaw 0.1.0

package/skills/pragma-delegation/SKILL.md

@@ -0,0 +1,300 @@
+---
+name: pragma-delegation
+description: Creates, renews, and manages on-chain trading delegations. Use when user needs to authorize trading, delegation expired, user wants to change trading scope, or after initial setup.
+tools:
+  - pragma_has_wallet
+  - pragma_get_account_info
+  - pragma_get_all_balances
+  - pragma_check_session_key_balance
+  - pragma_setup_session
+  - pragma_request_delegation
+  - pragma_poll_delegation
+  - pragma_retrieve_delegation
+  - pragma_wrap
+requires:
+  - pragma
+metadata:
+  openclaw:
+    requires: ["pragma"]
+---
+
+# Pragma Delegation — Trading Authorization
+
+> Creates and manages on-chain delegations that authorize the agent to trade on behalf of the user.
+
+## What Is a Delegation?
+
+A delegation is a signed on-chain permission from the user that lets you (the agent) trade through their Smart Account. Think of it like a power of attorney with built-in limits.
+
+**What the user is signing:**
+- Which actions you can perform (swap, trade perps, buy memecoins, etc.)
+- How long the permission lasts (e.g., 7 days)
+- Maximum MON per single transaction (e.g., 1 MON — this caps any single trade)
+- Total number of transactions allowed (e.g., 100)
+- Who can receive transfers (session key only, by default)
+
+**What you cannot do even with a delegation:**
+- Exceed the value limit per transaction
+- Call contracts not in the allowed list
+- Operate after the delegation expires
+- Transfer to addresses not whitelisted
+
+The user approves by signing with their passkey at pr4gma.xyz. You cannot bypass or modify the scope after signing.
+
+---
+
+## When This Skill Activates
+
+- After initial setup (pragma-setup completed, delegation needed)
+- A `pragma_` tool returns "Delegation expired" or "No delegation found"
+- User wants to change trading scope
+- User explicitly asks to "delegate", "authorize", "set permissions"
+
+---
+
+## Step 0: Check Existing Delegation
+
+Before creating a new delegation, check if one already exists. The MCP tools automatically use the stored delegation at `~/.pragma/delegations/root/delegation.json`.
+
+**ONLY create a new delegation if:**
+- A `pragma_` tool returns "Delegation expired" or "No delegation found"
+- The user explicitly asks to create or renew a delegation
+- This is the first-time setup flow (no delegation has ever been created)
+
+**DO NOT** create a new delegation just because you're about to perform a trade. Try the trade first — the existing delegation is used automatically.
+
+---
+
+## Step 1: Prerequisites
+
+```
+pragma_has_wallet → Must be true (if not, direct to pragma-setup first)
+pragma_get_account_info → Need the Smart Account address
+pragma_check_session_key_balance → Need gas (> 0.1 MON)
+```
+
+If session key gas is low, tell the user:
+  "Your session key needs gas to execute transactions.
+   Send at least 0.5 MON to: [session key address]"
+
+---
+
+## Step 2: Understand What the User Wants
+
+**DO NOT dump a list of presets.** Instead, ask a simple question:
+
+> "What would you like me to be able to do? For example: trade memecoins, do leveraged trading, swap tokens, or everything?"
+
+Then map the user's intent to the right scope:
+
+| User says... | You should use | Why |
+|-------------|----------------|-----|
+| "trade memecoins" / "snipe" / "nad.fun" | `["nadfun", "dex", "wmon"]` | Buying on bonding curve needs nadfun. Selling graduated tokens needs DEX. Wrapping needed for MON→WMON. |
+| "perps" / "leverage" / "leverup" | `["leverup", "dex", "wmon"]` | Perps need leverup. DEX for collateral swaps (MON↔LVUSD). Wrapping for MON. |
+| "swap tokens" / "spot trading" | `["dex", "wmon"]` | DEX for swaps. Wrapping for MON↔WMON. |
+| "everything" / "full access" / no preference | `["dex", "leverup", "nadfun", "wmon"]` | All protocols. |
+| Specific protocol names | Map directly | User knows what they want. |
+
+**Important:** `wmon` (wrap/unwrap) should almost always be included — most operations need MON↔WMON conversion at some point.
+
+---
+
+## Step 3: Set Parameters (Smart Defaults)
+
+Ask the user about limits using **plain language**, not parameter names. Use their portfolio to suggest smart defaults:
+
+```
+pragma_get_all_balances → Check portfolio size
+```
+
+### Duration
+
+> "How long should this authorization last?"
+
+| User says | `expiryDays` value |
+|-----------|-------------------|
+| "a few hours" / "just today" | 1 |
+| "a week" / nothing specified | 7 (default) |
+| "a month" / "longer" | 30 |
+
+### Max value per transaction
+
+> "What's the most MON I should be able to use in a single transaction?"
+
+**Smart defaults based on portfolio:**
+
+| Portfolio MON balance | Suggested `maxValuePerTxMon` |
+|----------------------|------------------------------|
+| < 5 MON | 0.5 |
+| 5–50 MON | 1 (default) |
+| 50–500 MON | 5 |
+| > 500 MON | 10 |
+
+Explain it simply:
+> "This caps any single trade at [X] MON. You have [Y] MON in your portfolio, so I'd suggest [Z] as the limit. Sound good?"
+
+### Max transactions
+
+> "How many transactions should I be allowed to make?"
+
+| Usage pattern | Suggested `maxCalls` |
+|--------------|---------------------|
+| Casual / first time | 50 |
+| Active trading | 100 (default) |
+| Autonomous / long duration | 500 |
+| Heavy usage | 1000 |
+
+Explain it simply:
+> "This is the total number of on-chain actions I can take — each swap, trade open/close, or approval counts as one. I'd suggest [X] for [duration] days."
+
+### Transfer recipients
+
+Transfers to the session key are enabled by default — this lets the agent fund its own gas. You don't need to ask the user about this unless they specifically want to restrict transfers.
+
+If the user asks about transfers to other addresses:
+> "By default, I can only transfer tokens to my own session key (for gas). Want to add other addresses I can send to?"
+
+---
+
+## Step 4: Confirm Before Submitting
+
+Summarize in plain language:
+
+```
+"Here's what I'm requesting permission for:
+
+ What I can do: [plain description, e.g., 'swap tokens, trade perps, and buy memecoins']
+ Duration: [X] days (expires [date])
+ Max per trade: [X] MON
+ Max transactions: [X] total
+ Self-funding: Enabled (I can send tokens/MON to my session key for gas)
+
+ You'll get a link to approve this in your browser.
+ Want me to proceed?"
+```
+
+Wait for user confirmation.
+
+---
+
+## Step 5: Submit Delegation Request
+
+```
+pragma_request_delegation({
+  sa: "<user's Smart Account address>",
+  protocols: ["dex", "leverup", "nadfun", "wmon"],
+  expiryDays: 7,
+  maxCalls: 100,
+  maxValuePerTxMon: 1,
+  budgetMon: 1,
+  description: "Full trading suite - 7 days"
+})
+→ Returns: { requestId, approvalUrl }
+```
+
+Send the approval URL with a clear explanation:
+
+```
+"Please approve this in your browser:
+ [approvalUrl]
+
+ What you're signing: A time-limited permission for me to trade
+ on your behalf with the limits we just discussed. I cannot
+ exceed these limits — they're enforced on-chain.
+
+ The link expires in 30 minutes."
+```
+
+---
+
+## Step 6: Poll for Approval
+
+```
+Poll every 30 seconds (max 30 minutes):
+  pragma_poll_delegation({ requestId })
+  → "pending": Continue polling silently
+  → "approved": Continue to Step 7
+  → "rejected": "Delegation rejected. Want to try different settings?"
+  → "expired": "The approval link expired. I'll create a new one."
+```
+
+If the user hasn't approved after 5 minutes, send a gentle reminder:
+  "Still waiting for your approval. Open this link when ready: [approvalUrl]"
+
+---
+
+## Step 7: Retrieve, Verify, and Activate
+
+```
+pragma_retrieve_delegation({ requestId })
+→ Signed delegation stored at ~/.pragma/delegations/root/delegation.json
+```
+
+**Verify the delegation works** with a small test:
+
+```
+pragma_wrap({ amount: "0.001" })
+→ If this succeeds, the delegation is working correctly
+→ If this fails with "No delegation found", something went wrong with storage
+```
+
+Then show the user:
+
+```
+pragma_get_all_balances → Portfolio snapshot
+
+"Delegation active and verified!
+
+ Valid until: [expiry date]
+ Scope: [what you can do]
+ Transactions remaining: [maxCalls]
+ Portfolio: [summary]
+
+ You can now ask me to trade. Try: 'what's trending on nad.fun?' or 'show my positions'"
+```
+
+---
+
+## Delegation Renewal
+
+When a delegation is expiring or expired:
+
+1. Check if the user wants the same scope or different
+2. If same scope, skip Step 2-3 and go straight to Step 5 with the same parameters
+3. If different scope, go through Steps 2-5
+
+```
+"Your trading authorization expires in [X hours / has expired].
+ Want me to renew with the same settings, or change anything?"
+```
+
+For autonomous mode: if the user doesn't respond within 30 minutes and the delegation is about to expire, close any open positions before the delegation expires.
+
+---
+
+## Protocol Reference
+
+| Protocol | What it does | Common operations |
+|----------|-------------|-------------------|
+| `dex` | Token swaps via DEX aggregator | Swap MON→USDC, swap any token pair |
+| `leverup` | Leveraged perpetual trading | Open/close positions, set TP/SL, limit orders |
+| `nadfun` | Memecoin trading on bonding curves | Buy/sell memecoins on nad.fun |
+| `wmon` | MON↔WMON wrapping | Convert native MON to wrapped MON and back |
+
+**Automatically included in every delegation (no configuration needed):**
+- ERC-20 token approvals (needed before swaps/trades)
+- ERC-20 transfers to session key (for self-funding with tokens)
+- Native MON transfers to session key (for gas self-funding)
+
+---
+
+## Error Handling
+
+| Error | What to tell the user |
+|-------|----------------------|
+| "Wallet not configured" | "You need to set up your wallet first. Say 'set up pragma' to get started." |
+| "Session key not registered" | "Your session key needs to be linked to your Smart Account. Let me fix that." → Run `pragma_setup_session` |
+| "Invalid Smart Account" | "That doesn't look like a valid Smart Account address. Can you double-check?" |
+| "Approval link expired" | "The link expired — let me create a fresh one." → Re-run Step 5 |
+| "Delegation rejected" | "No problem. Want to try with different settings, or skip for now?" |
+| "API error" | Retry once silently. If still fails: "Having trouble reaching the server. Let's try again in a moment." |

package/skills/pragma-mode/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: pragma-mode
+description: Switch between BYOK (free, bring your own keys) and x402 (pay per API call) modes.
+tools:
+  - pragma_has_providers
+  - pragma_set_mode
+requires:
+  - pragma
+metadata:
+  openclaw:
+    requires: ["pragma"]
+---
+
+# Pragma Mode — BYOK / x402 Switching
+
+> Switch between free (BYOK) and paid (x402) API modes.
+
+## Modes
+
+| Mode | Description | Cost |
+|------|-------------|------|
+| **x402** | All API backends provided by Pragma | Pay per API call |
+| **BYOK** | Bring your own API keys | Free (you provide everything) |
+
+## Switching
+
+```
+User: "switch to byok" / "use free mode" / "bring my own keys"
+→ pragma_set_mode({ mode: "byok" })
+
+User: "switch to x402" / "use paid mode" / "use convenience mode"
+→ pragma_set_mode({ mode: "x402" })
+```
+
+## After Switching
+
+After switching to BYOK, check provider status:
+```
+pragma_has_providers → Shows which providers are configured
+```
+
+If providers are missing, guide the user to configure them.

package/skills/pragma-setup/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: pragma-setup
+description: First-time onboarding for Pragma. Use when user needs to set up their wallet, configure the plugin, or hasn't used Pragma before.
+tools:
+  - pragma_has_wallet
+  - pragma_has_providers
+  - pragma_setup_wallet
+  - pragma_set_mode
+  - pragma_get_account_info
+  - pragma_get_all_balances
+  - pragma_check_session_key_balance
+  - pragma_setup_session
+requires:
+  - pragma
+metadata:
+  openclaw:
+    requires: ["pragma"]
+---
+
+# Pragma Setup — Onboarding
+
+> First-time setup for Pragma on OpenClaw.
+
+## When This Skill Activates
+
+- User says "set up pragma", "configure wallet", "get started"
+- `pragma_has_wallet` returns false
+- First interaction with any pragma tool fails due to missing wallet
+
+---
+
+## Onboarding Flow
+
+### Step 1: Check Current State
+
+```
+pragma_has_wallet
+  → true (with SA set): Skip to Step 5 (verify setup)
+  → true (no SA): Skip to Step 3 (ask for SA address)
+  → false: Continue to Step 2
+```
+
+### Step 2: Initialize Session Key
+
+```
+pragma_setup_wallet
+  → Creates file-based session key at ~/.pragma/session-key.json
+  → Creates config at ~/.pragma/config.json
+  → Returns: { sessionKeyAddress, smartAccountAddress: "not set" }
+```
+
+The session key is the agent's wallet — it will execute trades on behalf of the user.
+
+### Step 3: Get User's Smart Account Address
+
+The user needs a Pragma Smart Account. This is their on-chain wallet that the agent trades through.
+
+```
+Tell user:
+  "Session key created: [sessionKeyAddress]
+
+   Now I need your Smart Account (SA) address to connect.
+
+   If you already have one, paste the 0x... address here.
+
+   If you don't have one yet, create it at:
+   https://pr4gma.xyz/setup
+
+   It only takes a minute — just connect with your passkey."
+```
+
+Wait for user to provide their SA address (0x...).
+
+### Step 4: Register Session Key
+
+```
+pragma_setup_session({ sa: "<user's SA address>" })
+  → Registers session key with Pragma API
+  → Links session key to user's Smart Account
+  → Unlocks 50 free bootstrap API calls (x402 mode)
+```
+
+**Important:** Registration gives the session key 50 free x402 API calls. This means the agent can immediately check balances, get quotes, and fetch market data without the user needing to fund anything upfront.
+
+Tell the user:
+  "Session key registered and linked to your Smart Account.
+   You have 50 free API calls to get started."
+
+### Step 5: Verify Setup
+
+```
+pragma_get_all_balances → Portfolio check
+pragma_check_session_key_balance → Gas check
+```
+
+Show the user their portfolio summary and session key gas balance.
+
+If session key gas is low (< 0.1 MON):
+  "Your session key needs gas to execute transactions.
+   Send at least 0.5 MON to: [session key address]"
+
+**Gas funding rules for this platform:**
+- **First time (no delegation yet):** User must send MON manually to the session key address. There is no other way.
+- **After delegation is active:** Use `pragma_fund_session_key` to auto-transfer MON from SA → session key via delegation.
+- **Zero gas emergency:** If session key hits 0 MON, self-funding can't work (needs gas to submit the tx). Ask user to send MON manually.
+- **No UserOp on this platform.** Do not mention UserOp or bundler to the user.
+
+### Step 6: Create Trading Delegation
+
+If the user already has a delegation stored at `~/.pragma/delegations/root/delegation.json`, skip this step — the MCP tools will use it automatically.
+
+The user needs a delegation to authorize trading. Use the **pragma-delegation** skill.
+
+The delegation skill will:
+1. Ask the user what they want to trade (maps to protocol scopes automatically)
+2. Set duration, limits, and gas budget using smart defaults
+3. Submit the delegation request with proper on-chain caveats (includes transfer groups for session key self-funding by default)
+4. Send the user an approval link to sign with their passkey
+5. Poll for approval and retrieve the signed delegation
+6. Verify the delegation works with a small test transaction
+
+```
+Tell user:
+  "Now let's set up your trading authorization.
+   I'll ask you a few questions about what you'd like me to trade."
+```
+
+Follow the pragma-delegation skill flow from Step 2 onward.
+
+### Step 7: Done
+
+After delegation is active:
+
+```
+Tell user:
+  "Setup complete!
+
+   Smart Account: [SA address]
+   Session Key: [session key address]
+   Delegation: Active until [expiry]
+   Portfolio: [summary]
+
+   You can now ask me to trade, check prices, or monitor markets.
+   Try: 'show my portfolio' or 'what's trending on nad.fun?'"
+```
+
+---
+
+## Mode Configuration
+
+Default mode is **x402** (paid convenience). The user can switch to BYOK (free, bring your own keys) at any time using the **pragma-mode** skill.
+
+---
+
+## Troubleshooting
+
+| Issue | Solution |
+|-------|----------|
+| "Wallet not found" | Run setup from Step 2 |
+| "Session key not registered" | Run `pragma_setup_session` with SA address |
+| "Delegation expired" | Use pragma-delegation skill to create new delegation |
+| "Insufficient gas" | "Send MON to session key: [address]" |
+| "No balance" | "Send tokens to Smart Account: [address]" |
+| "Bootstrap calls exhausted" | User needs to fund session key for x402 payments |