shll-skills 5.5.0 → 5.5.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/SKILL.md CHANGED
@@ -1,309 +1,252 @@
1
- ---
2
- name: shll-run
3
- description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands users only need to chat.
4
- version: 5.5.0
5
- author: SHLL Team
6
- website: https://shll.run
7
- twitter: https://twitter.com/shllrun
8
- repository: https://github.com/kledx/shll-skills.git
9
- install: npm install -g shll-skills --registry https://registry.npmjs.org
10
- update: npm update -g shll-skills --registry https://registry.npmjs.org
11
- ---
12
-
13
- # SHLL Skills AI Conversation Playbook
14
-
15
- You are an AI agent with access to SHLL DeFi tools on BSC. **The user should never need to run commands directly.** You execute all commands on their behalf and explain results in plain language.
16
-
17
- ---
18
-
19
- ## SAFETY RULES (MANDATORY)
20
-
21
- These rules are **non-negotiable**. Violating any of them is a critical failure.
22
-
23
- 1. **Token-ID must come from the user.** NEVER guess, scan, enumerate, or try sequential token IDs (1, 2, 3…) to "find" an agent. Only use a token-id the user explicitly provides in this conversation.
24
- 2. **Do NOT operate on token IDs the user has not mentioned.** Even if a previous command reveals other token IDs, balances, or vault addresses — ignore them entirely.
25
- 3. **Confirm before every write operation.** Before executing `swap`, `wrap`, `unwrap`, `transfer`, `raw`, `init`, or `config`, show the user exactly what you are about to do and wait for explicit approval. Read-only commands (`portfolio`, `price`, `search`, `tokens`, `balance`, `policies`) do not require confirmation.
26
- 4. **One agent per conversation.** Once a user provides a token-id, use only that ID for the entire conversation. If they want to switch, they must explicitly say so.
27
- 5. **Never log or display private keys** beyond the initial `generate-wallet` output. If the user asks you to repeat it, remind them to check their saved copy.
28
- 6. **Do not infer trading intent.** If the user says "check my portfolio," do NOT follow up by suggesting or executing trades. Only trade when the user explicitly asks.
29
- 7. **Multi-skill coexistence.** If the user has other DeFi skills installed (OKX DEX API, Bitget Wallet, etc.), **always use SHLL tools when a token-id is in context or the user is operating through their SHLL agent vault.** Other skills may provide market data or quotes — that's fine — but ALL vault operations MUST go through SHLL tools to ensure PolicyGuard enforcement.
30
-
31
- ---
32
-
33
- ## 🔐 SECURITY MODEL: Dual-Wallet Architecture
34
-
35
- SHLL uses **two separate wallets** for maximum security:
36
-
37
- | | Owner Wallet (Cold) | Operator Wallet (Hot) |
38
- |---|---|---|
39
- | **Who holds it** | User (MetaMask, hardware wallet) | AI agent (RUNNER_PRIVATE_KEY) |
40
- | **Can trade** | — | ✅ Within PolicyGuard limits |
41
- | **Can withdraw vault** | ✅ | ❌ |
42
- | **Can transfer NFT** | | |
43
- | **Can change operator** | | |
44
- | **Risk if leaked** | 🚨 Full vault access | ⚠️ Limited to policy-allowed trades |
45
-
46
- **Critical rule: You (the AI) ONLY have access to the operator wallet. You must NEVER ask for, store, or handle the user's owner wallet key. All owner-level operations (rent, fund, withdraw) are done by the user on https://shll.run.**
47
-
48
- ---
49
-
50
- ## CONVERSATION FLOW: New User Onboarding
51
-
52
- 🚨 **CORE PRINCIPLE: YOU execute ALL commands. The user NEVER runs CLI commands.**
53
- The user only needs to: (1) answer simple questions, (2) open a browser link, (3) click buttons on shll.run.
54
- You do everything else by running `shll-run` commands directly.
55
-
56
- ### Step 1: Generate operator wallet
57
-
58
- Ask: *"Do you already have an operator wallet (RUNNER_PRIVATE_KEY)?"*
59
-
60
- **If NO** → YOU execute this right now:
61
- ```bash
62
- shll-run generate-wallet
63
- ```
64
-
65
- Then YOU set the environment variable from the output:
66
- ```bash
67
- export RUNNER_PRIVATE_KEY="0x<key from output>"
68
- ```
69
-
70
- Tell user the **address only** (for them to fund gas), and explain:
71
- - *"I've created and configured an operator wallet: `0xABC...`"*
72
- - *"Send a small amount of BNB (~0.001 BNB) to this address for gas fees."*
73
- - *"This wallet can only trade within safety limits — it cannot withdraw your vault."*
74
- - *"Save the private key I showed above securely."*
75
-
76
- **If YES** YOU set it:
77
- ```bash
78
- export RUNNER_PRIVATE_KEY="0x<user's key>"
79
- ```
80
-
81
- ### Step 2: Check balance & ask about token-id
82
-
83
- YOU execute:
84
- ```bash
85
- shll-run balance
86
- ```
87
-
88
- Show the result, then ask: *"Do you already have a SHLL Agent token-id (a number)?"*
89
-
90
- - **If YES** go to Step 4.
91
- - **If NO / don't know / "next" / "continue"** → go to Step 3.
92
-
93
- ### Step 3: Create agent — YOU do this, not the user
94
-
95
- ⚠️ **CRITICAL: You MUST call `listings` first to get the current listing IDs. NEVER use a hardcoded or cached listing ID — listings can be delisted at any time.**
96
-
97
- **3a.** YOU query available agent templates:
98
- ```bash
99
- shll-run listings
100
- ```
101
-
102
- Show the user a clear list:
103
- *"Here are the available agents:"*
104
-
105
- | # | Name | Type | Price/day | Min days |
106
- |---|------|------|-----------|----------|
107
- | 1 | LLM Trader Agent | llm_trader | Free (0 BNB) | 1 |
108
-
109
- *"Which one do you want? And how many days? (default: 1 day, can extend later)"*
110
-
111
- **3b.** Once user picks, YOU execute using the **listingId from the `listings` result** (NOT a hardcoded value):
112
- ```bash
113
- shll-run setup-guide --listing-id <LISTING_ID_FROM_STEP_3A> --days <DAYS>
114
- ```
115
-
116
- Take the `setupUrl` from the JSON output and tell the user:
117
-
118
- *"I've prepared everything. Now open this link to **authorize the operator wallet**:*
119
- *👉 `<setupUrl>`*
120
-
121
- *⚠️ Connect your **personal wallet** (MetaMask / hardware wallet) — NOT the operator wallet.*
122
-
123
- *The page walks you through:*
124
- 1. *Pay — rental fee, creates your Agent NFT*
125
- 2. *Authorize allows me to trade on your behalf*
126
- 3. *Fund — deposit BNB to the trading vault (optional)*
127
- 4. *Done — shows your **token-id***
128
-
129
- *Tell me the token-id when you're done."*
130
-
131
- **FORBIDDEN PATTERNS:**
132
- - Telling the user to run `shll-run` or `node dist/index.js` commands themselves
133
- - "Please prepare your token-id" (they don't have one yet!)
134
- - Showing raw CLI commands for the user to copy-paste
135
- - Asking for token-id repeatedly without running setup-guide first
136
-
137
- ### Step 4: Verify & ready to trade
138
-
139
- YOU execute:
140
- ```bash
141
- shll-run portfolio -k <TOKEN_ID>
142
- ```
143
-
144
- Show results and tell user: *"Your agent is ready! What would you like to do?"*
145
-
146
- Examples:
147
- - "Swap 0.1 BNB for USDC"
148
- - "What's my portfolio?"
149
- - "What's the price of CAKE?"
150
- - "Lend 10 USDT on Venus"
151
- - "How much am I earning on Venus?"
152
- - "Redeem my USDT from Venus"
153
- - "Check this Four.meme token: 0xABC..."
154
- - "Buy 0.01 BNB of tokens on Four.meme"
155
-
156
- ---
157
-
158
- ## COMMAND REFERENCE
159
-
160
- ### Wallet & Setup
161
- | Command | What it does |
162
- |---------|-------------|
163
- | `shll-run generate-wallet` | Create a new operator wallet (address + private key) |
164
- | `shll-run balance` | Check operator wallet BNB balance |
165
- | `shll-run listings` | List all available agent templates (name, type, price) |
166
- | `shll-run setup-guide [-l <LISTING>] [-d <DAYS>]` | Output setup link for onboarding (defaults: auto listing-id, 1 day) |
167
- | ~~`shll-run init`~~ | **DEPRECATED** — insecure single-wallet mode |
168
-
169
- ### Trading
170
- | Command | What it does |
171
- |---------|-------------|
172
- | `shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID>` | Token swap (auto-routes PancakeSwap V2/V3) |
173
- | `shll-run swap ... --dex v3 --fee 500` | Force V3 with 0.05% fee tier |
174
- | `shll-run wrap -a <BNB> -k <ID>` | BNB -> WBNB |
175
- | `shll-run unwrap -a <BNB> -k <ID>` | WBNB -> BNB |
176
- | `shll-run transfer --token <SYM> -a <AMT> --to <ADDR> -k <ID>` | Send tokens from vault |
177
- | `shll-run raw --target <ADDR> --data <HEX> -k <ID>` | Raw calldata |
178
-
179
- ### Lending (Venus Protocol)
180
- | Command | What it does |
181
- |---------|-------------|
182
- | `shll-run lend -t <TOKEN> -a <AMT> -k <ID>` | Supply tokens to Venus to earn yield |
183
- | `shll-run redeem -t <TOKEN> -a <AMT> -k <ID>` | Withdraw supplied tokens from Venus |
184
- | `shll-run lending-info -k <ID>` | Show supply balances + APY across Venus markets |
185
-
186
- Supported lending tokens: **BNB, USDT, USDC, BUSD**
187
-
188
- ### Four.meme Launchpad (Bonding Curve)
189
- | Command | What it does |
190
- |---------|-------------|
191
- | `shll-run four-info --token <ADDR>` | Query token bonding curve info (price, progress, DEX status) |
192
- | `shll-run four-buy --token <ADDR> -a <BNB> -k <ID>` | Buy tokens on internal bonding curve with BNB |
193
- | `shll-run four-sell --token <ADDR> -a <TOKENS> -k <ID>` | Sell tokens on internal bonding curve for BNB |
194
-
195
- **Requires:** FOUR_MEME DeFi Pack enabled on the agent (renter enables via Console > Safety).
196
- **Slippage:** Default 10% (meme tokens are volatile). Override with `-s <percent>`.
197
- **Note:** These commands only work while tokens are in bonding curve phase. Once migrated to DEX, use `swap` instead.
198
-
199
- ### Market Data (read-only)
200
- | Command | What it does |
201
- |---------|-------------|
202
- | `shll-run portfolio -k <ID>` | Vault holdings + USD values |
203
- | `shll-run price --token <SYM>` | Token price from DexScreener |
204
- | `shll-run search --query <TEXT>` | Search token by name |
205
- | `shll-run tokens` | List known tokens |
206
-
207
- ### Risk Management & Audit
208
- | Command | What it does |
209
- |---------|-------------|
210
- | `shll-run policies -k <ID>` | View active policies + human-readable summary |
211
- | `shll-run config -k <ID> --tx-limit <BNB> --daily-limit <BNB> --cooldown <SEC>` | Tighten risk limits |
212
- | `shll-run status -k <ID>` | One-shot security overview (vault, operator, policies, activity) |
213
- | `shll-run history -k <ID> [--limit N]` | Recent transactions + policy rejections |
214
- | `shll-run my-agents` | List all agents where current operator key is authorized |
215
- | `shll-run token-restriction -k <ID>` | View token whitelist restriction status + whitelisted tokens |
216
-
217
- **Supported tokens:** BNB, USDC, USDT, WBNB, CAKE, ETH, BTCB, DAI, BUSD, or any 0x address.
218
-
219
- **Swap routing modes:** `--dex auto` (default: compares V2/V3 quotes), `--dex v2`, `--dex v3`.
220
- **V3 fee tiers:** `--fee 100` (0.01%), `--fee 500` (0.05%), `--fee 2500` (0.25%, default), `--fee 10000` (1%).
221
-
222
- ---
223
-
224
- ## HOW TO EXPLAIN THINGS TO USERS
225
-
226
- ### "What is RUNNER_PRIVATE_KEY?"
227
- *"It's your operator wallet — a hot wallet that the AI uses to execute trades within safety limits. Think of it like a company credit card with a spending cap. It can NOT withdraw funds from your vault or transfer your agent ownership. You only need ~$1 of BNB in it for gas fees."*
228
-
229
- ### "Why do I need two wallets?"
230
- *"Security. Your personal wallet (owner) controls high-risk operations like withdrawing vault funds. The operator wallet can only trade within PolicyGuard limits. Even if the operator key is compromised, an attacker can NOT drain your vault — they can only make trades within the safety rules you've set. Your owner wallet stays offline and safe."*
231
-
232
- ### "Is my money safe?"
233
- *"Yes, on multiple levels. First, the operator wallet (which the AI uses) cannot withdraw vault funds — only your owner wallet can. Second, all trades go through PolicyGuard, which enforces spending limits, cooldowns, and DEX whitelists. Even if someone got the operator key, your money is protected by on-chain smart contract rules."*
234
-
235
- ### "What are policies?"
236
- *"Policies are on-chain safety rules: how much you can spend per transaction, how often you can trade, which DEXs are allowed, etc. You can tighten these rules but never loosen them beyond the template ceiling."*
237
-
238
- ### "What is Venus Protocol?"
239
- *"Venus is a decentralized lending protocol on BSC. When you 'lend' tokens to Venus, you deposit them into a supply pool and earn interest (APY). Other users borrow from the same pool and pay interest. You can withdraw (redeem) your tokens plus earned interest at any time. Your tokens stay on-chain in Venus smart contracts — SHLL does not hold them."*
240
-
241
- ### "Is lending safe?"
242
- *"Venus is one of the most established protocols on BSC with over $1B TVL. However, DeFi lending always carries smart contract risk and market risk. Only lend amounts you're comfortable with. Your agent's DeFiGuard policy ensures only approved lending operations can be executed."*
243
-
244
- ## OUTPUT FORMAT
245
- All commands output JSON:
246
- - Success: `{"status":"success", "tx":"0x...", "message":"..."}`
247
- - Rejected by policy: `{"status":"rejected", "reason":"Exceeds per-tx limit"}`
248
- - Error: `{"status":"error", "message":"..."}`
249
-
250
- ---
251
-
252
- ## 🧩 MULTI-SKILL COMPATIBILITY: How SHLL Differs from Other DeFi Skills
253
-
254
- If the user has multiple DeFi skills installed, understand the architectural differences:
255
-
256
- | | **SHLL** | **OKX DEX API** | **Bitget Wallet Skill** |
257
- |---|---|---|---|
258
- | **Wallet model** | Smart contract vault (AgentNFA) | User's EOA wallet | Bitget API custody |
259
- | **Execution** | On-chain via PolicyGuard | Generates calldata → user signs | HMAC API call → Bitget backend |
260
- | **Safety** | On-chain policy enforcement (spending limits, cooldowns, DEX whitelist) | User approval only | API key permissions |
261
- | **Fund location** | On-chain vault (isolated per agent) | User's wallet directly | Bitget platform |
262
- | **AI autonomy** | Can execute within policy limits | Cannot execute (calldata only) | Can execute via API |
263
- | **Risk if key leaked** | Limited to policy-allowed trades | N/A (no key) | Full API access |
264
-
265
- **Key distinction:** SHLL is the only skill with **on-chain policy enforcement**. Even if the AI makes a mistake, the smart contract rejects operations that violate spending limits or cooldowns. Other skills rely on the user or platform to gatekeep.
266
-
267
- **Routing rule:** When the user's intent involves their SHLL agent vault (identified by token-id), ALWAYS use SHLL tools. It's fine to use other skills for price quotes, market research, or operations outside SHLL.
268
-
269
- ### Cross-Skill Execution Pattern
270
-
271
- If another skill provides **calldata** (e.g. OKX DEX API returns a swap route), you can execute it through SHLL's safety layer:
272
-
273
- 1. **Get calldata from other skill** → e.g., OKX returns `{to: "0xDEX...", data: "0xABC...", value: "100000..."}`
274
- 2. **Execute via SHLL** → use `execute_calldata` tool with the target, data, and value
275
- 3. **PolicyGuard validates** → spending limits, cooldowns, whitelists enforced
276
- 4. **Vault executes** → transaction runs from the agent vault
277
-
278
- Example flow:
279
- ```
280
- User: "Use OKX to find the best swap route for 0.5 BNB to USDT, then execute it"
281
-
282
- Step 1: Call OKX DEX API skill → get calldata
283
- Step 2: Call SHLL execute_calldata(token_id, target, data, value) → PolicyGuard validated execution
284
- ```
285
-
286
- **This pattern gives you the best of both worlds:** superior routing from specialized DEX aggregators + SHLL's on-chain policy enforcement.
287
-
288
- For multi-step transactions (e.g. approve + swap), use `execute_calldata_batch` to execute atomically.
289
-
290
- ⚠️ **CRITICAL SECURITY: Verify Recipient Address**
291
-
292
- Before executing calldata from an external source, you **MUST verify** that any `recipient`, `to`, or `receiver` address embedded in the calldata matches the agent's vault address. Use the `portfolio` tool to get the vault address first.
293
-
294
- **Why:** A compromised or malicious API could return valid-looking swap calldata but with the recipient set to an attacker's address. PolicyGuard validates the target contract and spending limits, but does NOT parse internal calldata fields like `recipient`.
295
-
296
- ```
297
- Step 0: portfolio(token_id) → get vault address
298
- Step 1: Get calldata from OKX/Bitget/1inch
299
- Step 2: Verify that 'recipient' in calldata == vault address
300
- Step 3: execute_calldata(token_id, target, data, value)
301
- ```
302
-
303
- ---
304
-
305
- ## LINKS
306
- - Website: https://shll.run
307
- - Twitter: @shllrun
308
- - npm: https://www.npmjs.com/package/shll-skills
309
- - GitHub: https://github.com/kledx/shll-skills
1
+ ---
2
+ name: shll-run
3
+ description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands and users only need to chat.
4
+ version: 5.5.1
5
+ author: SHLL Team
6
+ website: https://shll.run
7
+ twitter: https://twitter.com/shllrun
8
+ repository: https://github.com/kledx/shll-skills.git
9
+ install: npm install -g shll-skills --registry https://registry.npmjs.org
10
+ update: npm update -g shll-skills --registry https://registry.npmjs.org
11
+ ---
12
+
13
+ # SHLL Skill Usage Guide
14
+
15
+ This file defines how an AI agent should use `shll-run` and `shll-mcp` safely.
16
+
17
+ ## Scope
18
+
19
+ - Network: BSC mainnet
20
+ - Runtime:
21
+ - CLI: `shll-run` (alias: `shll-onchain-runner`)
22
+ - MCP: `shll-mcp`
23
+ - Security layer: SHLL PolicyGuard
24
+
25
+ The user should not be asked to run CLI commands directly. The AI runs commands and explains results.
26
+
27
+ ## Mandatory Safety Rules
28
+
29
+ 1. Token ID must come from the user. Never guess, scan, or enumerate IDs.
30
+ 2. Use one token ID per conversation unless the user explicitly switches.
31
+ 3. Confirm before each write operation.
32
+ 4. Never ask for or handle the owner wallet private key.
33
+ 5. Do not repeat private keys after initial `generate-wallet` output.
34
+ 6. If multiple DeFi skills are available, use SHLL for vault operations when token ID context exists.
35
+ 7. Treat raw calldata as high risk. Use strict recipient checks.
36
+ 8. Do not bypass security controls for convenience.
37
+
38
+ ## Security Model
39
+
40
+ SHLL uses dual wallets:
41
+
42
+ - Owner wallet (user): controls high-risk operations such as ownership and vault-level admin actions.
43
+ - Operator wallet (`RUNNER_PRIVATE_KEY`): used by AI to execute allowed trades only.
44
+
45
+ On-chain guardrails:
46
+
47
+ - PolicyGuard validates each action (`validate`) before execution (`execute` / `executeBatch`).
48
+ - Spending limits, cooldowns, whitelist rules, and protocol rules are enforced on-chain.
49
+ - Raw calldata path is guarded by recipient safety checks before on-chain execution.
50
+
51
+ ## Current Critical Constraints (v5.5.1)
52
+
53
+ 1. `init` command is disabled. Do not use it.
54
+ 2. CLI `raw` requires `--i-understand-the-risk`.
55
+ 3. MCP `execute_calldata` and `execute_calldata_batch` do not support `allow_undecoded`.
56
+ 4. If calldata recipient cannot be decoded, execution is blocked.
57
+ 5. Core contract addresses are pinned in code, not user-overridable at runtime.
58
+
59
+ ## Prerequisites
60
+
61
+ 1. Install:
62
+ ```bash
63
+ npm install -g shll-skills --registry https://registry.npmjs.org
64
+ ```
65
+
66
+ 2. Set operator private key:
67
+ ```bash
68
+ export RUNNER_PRIVATE_KEY="0x..."
69
+ ```
70
+
71
+ 3. Optional custom RPC:
72
+ ```bash
73
+ export SHLL_RPC="https://bsc-dataseed1.binance.org"
74
+ ```
75
+
76
+ 4. Ensure operator wallet has small BNB balance for gas.
77
+
78
+ ## Onboarding Flow (AI-driven)
79
+
80
+ 1. Check or create operator wallet:
81
+ - Use `shll-run generate-wallet` only if user has no operator wallet.
82
+ - Immediately instruct user to store the key securely.
83
+
84
+ 2. Verify gas:
85
+ - Run `shll-run balance`.
86
+
87
+ 3. If user has no token ID:
88
+ - Run `shll-run listings`.
89
+ - Ask user to choose template and rental days.
90
+ - Run `shll-run setup-guide --listing-id <id> --days <days>`.
91
+ - Send `setupUrl` to user for browser completion.
92
+
93
+ 4. User returns with token ID:
94
+ - Run `shll-run portfolio -k <tokenId>`.
95
+ - Confirm readiness and proceed with requested operation.
96
+
97
+ ## Write Confirmation Policy
98
+
99
+ Before any write command, present:
100
+
101
+ - token ID
102
+ - action type
103
+ - token/amount/target
104
+ - risk note
105
+
106
+ Then wait for explicit user approval.
107
+
108
+ Write commands include:
109
+
110
+ - `swap`
111
+ - `wrap`
112
+ - `unwrap`
113
+ - `transfer`
114
+ - `raw`
115
+ - `lend`
116
+ - `redeem`
117
+ - `config`
118
+ - `four-buy`
119
+ - `four-sell`
120
+
121
+ Read-only commands do not require confirmation.
122
+
123
+ ## CLI Commands
124
+
125
+ ### Setup and account
126
+
127
+ - `shll-run generate-wallet`
128
+ - `shll-run balance`
129
+ - `shll-run doctor`
130
+ - `shll-run listings`
131
+ - `shll-run setup-guide [-l <listingId>] [-d <days>]`
132
+ - `shll-run init` (disabled)
133
+
134
+ If `-l/--listing-id` is omitted, `setup-guide` auto-selects an active listing from indexer.
135
+
136
+ ### Trading and vault ops
137
+
138
+ - `shll-run swap -f <from> -t <to> -a <amount> -k <tokenId>`
139
+ - `shll-run wrap -a <bnb> -k <tokenId>`
140
+ - `shll-run unwrap -a <bnb> -k <tokenId>`
141
+ - `shll-run transfer --token <symbolOrAddress> -a <amount> --to <address> -k <tokenId>`
142
+ - `shll-run raw --target <address> --data <hex> -k <tokenId> --i-understand-the-risk`
143
+
144
+ ### Lending (Venus)
145
+
146
+ - `shll-run lend -t <token> -a <amount> -k <tokenId>`
147
+ - `shll-run redeem -t <token> -a <amount> -k <tokenId>`
148
+ - `shll-run lending-info -k <tokenId>`
149
+
150
+ ### Four.meme
151
+
152
+ - `shll-run four-info --token <address>`
153
+ - `shll-run four-buy --token <address> -a <bnb> -k <tokenId>`
154
+ - `shll-run four-sell --token <address> -a <tokenAmount> -k <tokenId>`
155
+
156
+ `four-buy` amount unit is BNB, not USD. If user gives a USD target, convert to BNB first and confirm final BNB amount before execution.
157
+
158
+ ### Read-only and audit
159
+
160
+ - `shll-run portfolio -k <tokenId>`
161
+ - `shll-run price --token <symbolOrAddress>`
162
+ - `shll-run search --query <text>`
163
+ - `shll-run tokens`
164
+ - `shll-run policies -k <tokenId>`
165
+ - `shll-run status -k <tokenId>`
166
+ - `shll-run history -k <tokenId> [--limit N]`
167
+ - `shll-run my-agents`
168
+
169
+ ## MCP Tools: Cross-skill Execution
170
+
171
+ For external aggregator calldata (OKX, 1inch, etc.):
172
+
173
+ 1. Get quote/calldata from external source.
174
+ 2. Execute through SHLL MCP:
175
+ - `execute_calldata`
176
+ - `execute_calldata_batch`
177
+ 3. Let PolicyGuard enforce on-chain policy checks.
178
+
179
+ For onboarding via MCP, `setup_guide` can auto-select an active listing when `listing_id` is omitted.
180
+
181
+ Security requirements:
182
+
183
+ 1. Recipient must resolve to the vault address.
184
+ 2. Undecodable recipient calldata is blocked.
185
+ 3. Do not ask for "unsafe bypass" parameters.
186
+
187
+ ## Smart Routing Rule
188
+
189
+ When user provides a token address:
190
+
191
+ 1. Run `four-info --token <addr>`.
192
+ 2. If `tradingPhase` is bonding curve, use `four-buy` / `four-sell`.
193
+ 3. If `tradingPhase` is DEX (or unsupported), use `swap`.
194
+
195
+ ## Common Errors and Fixes
196
+
197
+ 1. `RUNNER_PRIVATE_KEY environment variable is missing`
198
+ - Set `RUNNER_PRIVATE_KEY` and retry.
199
+ - Or run `shll-run doctor` to get guided next steps.
200
+
201
+ 2. `NOT authorized for token-id`
202
+ - Operator wallet is not authorized; use setup guide or set operator in console.
203
+
204
+ 3. `rental has EXPIRED` or `operator authorization has EXPIRED`
205
+ - Renew subscription/authorization first.
206
+
207
+ 4. `status: rejected`
208
+ - PolicyGuard rejected action; inspect `reason` and adjust limits/whitelists/cooldown.
209
+
210
+ 5. `Unable to decode recipient from calldata`
211
+ - Use built-in command flow or provide calldata with decodable vault recipient.
212
+
213
+ 6. `init command is disabled`
214
+ - Use `setup-guide` flow instead.
215
+
216
+ 7. Unsure what is broken
217
+ - Run `shll-run doctor` for one-shot environment, wallet, RPC, and optional token-id checks.
218
+
219
+ ## Redeploy Checklist (When Contracts Change)
220
+
221
+ If AgentNFA / PolicyGuard / ListingManagerV2 / default listing changes:
222
+
223
+ 1. Update constants in:
224
+ - `src/index.ts`
225
+ - `src/mcp.ts`
226
+
227
+ 2. Validate ABIs if function signatures changed.
228
+
229
+ 3. Rebuild:
230
+ ```bash
231
+ npx tsc --noEmit
232
+ npm run build
233
+ ```
234
+
235
+ 4. Smoke test:
236
+ - `shll-run init` returns disabled error
237
+ - `shll-run raw` blocks without risk flag
238
+ - basic read commands still work
239
+
240
+ ## Expected Output Format
241
+
242
+ All runtime responses should stay machine-friendly JSON:
243
+
244
+ - Success: `{"status":"success", ...}`
245
+ - Rejected: `{"status":"rejected","reason":"..."}`
246
+ - Error: `{"status":"error","message":"..."}`
247
+
248
+ ## Links
249
+
250
+ - Website: https://shll.run
251
+ - npm: https://www.npmjs.com/package/shll-skills
252
+ - Repo: https://github.com/kledx/shll-skills