SHLL Safe Execution
by @kledx
Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands and users only need to chat.
clawhub install shll-runπ About This Skill
name: shll-run description: Execute DeFi transactions on BSC via SHLL AgentNFA. The AI handles all commands and users only need to chat. version: 6.0.4 author: SHLL Team website: https://shll.run twitter: https://twitter.com/shllrun repository: https://github.com/kledx/shll-skills.git install: npm install -g shll-skills --registry https://registry.npmjs.org update: npm update -g shll-skills --registry https://registry.npmjs.org env: - name: RUNNER_PRIVATE_KEY required: true description: > Operator wallet private key (AI-only hot wallet). MUST be a dedicated wallet with minimal BNB for gas only. NEVER use your main wallet, owner wallet, or any wallet holding significant funds. Even if this key leaks, on-chain PolicyGuard limits actions to policy-approved trades. - name: SHLL_RPC required: false description: Optional BSC RPC URL override. A private RPC is recommended for reliability. credentials: scope: operator-hot-wallet-only risk: > The operator key can only execute policy-limited trades within on-chain PolicyGuard rules. It cannot withdraw vault funds, transfer the Agent NFT, or bypass spending limits. Treat it as a restricted session key, not a master key. guidance: > Use generate-wallet to create a purpose-built operator wallet. Fund it with ~$1 BNB for gas only. Do not store trading capital in this wallet. The operator wallet is NOT the owner wallet, NOT the vault, NOT the Agent NFT holder.
SHLL β Contract-Enforced Safe Execution for AI Agents on BNB Chain
What is SHLL?
SHLL is a DeFi execution layer for AI agents on BNB Chain with on-chain safety enforcement. Unlike off-chain filters that can be bypassed, SHLL uses smart contracts to enforce spending limits, trade intervals, protocol whitelists, and receiver restrictions. Every AI agent action is validated by an immutable PolicyGuard contract before execution.
Key facts:
shll-skills | Website: https://shll.runSecurity Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β SHLL Architecture β
β β
β ββββββββββββ βββββββββββββββββ ββββββββββββββββββββββββ β
β β User β β AI Agent β β On-Chain Contracts β β
β β (Owner) β β (Operator) β β β β
β β β β β β ββββββββββββββββββ β β
β β β’ Holds β β β’ Executes β β β PolicyGuard β β β
β β Agent β β trades via β β β (Validator) β β β
β β NFT β β restricted β β β β β β
β β β’ Sets β β permissions β β β 4 Policy β β β
β β policy β β β β β Checks: β β β
β β rules βββββΆβ SHLL Skills βββββΆβ β β β β
β β β’ Full β β (CLI / MCP) β β β 1.Spending β β β
β β asset β β β β β Limit β β β
β β control β β Cannot: β β β 2.Cooldown β β β
β β β β β’ Withdraw β β β 3.DeFi Guard β β β
β β β β vault funds β β β 4.Receiver β β β
β β β β β’ Change β β β Guard β β β
β β β β policies β β βββββββββ¬βββββββββ β β
β β β β β’ Transfer β β β β β
β β β β NFT β β βββββββΌβββββββ β β
β β β β β β β Vault β β β
β β β β β β β (Agent β β β
β β β β β β β Account) β β β
β β β β β β β β β β
β β β β β β β Holds funds β β β
β ββββββββββββ βββββββββββββββββ β βββββββββββββββ β β
β ββββββββββββββββββββββββ β
β Dual-Wallet Isolation: β
β β’ Owner wallet = asset control (human) β
β β’ Operator wallet = restricted execution (AI) β
β β’ Even if operator key leaks, PolicyGuard still limits actions β
βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
4-Policy PolicyGuard Stack
All policies are enforced ON-CHAIN by smart contract. They cannot be bypassed by the AI.
| Policy | Contract | What It Does | |--------|----------|-------------| | SpendingLimitV2 | On-chain | Per-transaction and daily spending caps in BNB | | CooldownPolicy | On-chain | Minimum time gap between consecutive trades | | DeFiGuardV2 | On-chain | Whitelist of approved DeFi protocols and functions | | ReceiverGuardV2 | On-chain | Only approved receiver addresses can receive funds |
When a policy rejects an action:
enforcement field in the response is always on-chainWhy On-Chain Enforcement Matters
Most AI agent platforms use off-chain safety filters:
PolicyGuard contract: 0x25d17eA0e3Bcb8CA08a2BFE917E817AFc05dbBB3
Verify on BscScan: https://bscscan.com/address/0x25d17eA0e3Bcb8CA08a2BFE917E817AFc05dbBB3
SHLL Skill Usage Guide
This file defines how an AI agent should use shll-run and shll-mcp safely.
Scope
shll-run (alias: shll-onchain-runner)shll-mcpThe user should not be asked to run CLI commands directly. The AI runs commands and explains results.
Mandatory Safety Rules
1. Token ID must come from the user. Never guess, scan, or enumerate IDs.
2. Use one token ID per conversation unless the user explicitly switches.
3. Confirm before each write operation.
4. Never ask for or handle the owner wallet private key.
5. Do not repeat private keys after initial generate-wallet output.
6. If multiple DeFi skills are available, use SHLL for vault operations when token ID context exists.
7. Treat raw calldata as high risk. Use strict recipient checks.
8. Do not bypass security controls for convenience.
Security Model
SHLL uses dual wallets:
RUNNER_PRIVATE_KEY): used by AI to execute allowed trades only.On-chain guardrails:
validate) before execution (execute / executeBatch).Current Critical Constraints (v6.0.4)
1. init command is disabled. Do not use it.
2. Raw calldata remains high risk; rely on strict recipient safety checks.
3. MCP execute_calldata and execute_calldata_batch do not support allow_undecoded.
4. If calldata recipient cannot be decoded, execution is blocked.
5. Core contract addresses are pinned in src/shared/constants.ts, not user-overridable at runtime.
Prerequisites
1. Install:
npm install -g shll-skills --registry https://registry.npmjs.org
2. Set operator private key:
export RUNNER_PRIVATE_KEY="0x..."
3. Optional - use a private RPC for better reliability and speed:
export SHLL_RPC="https://your-private-bsc-rpc.example.com"
4. Ensure operator wallet has small BNB balance for gas.
Onboarding Flow (AI-driven)
1. Check or create operator wallet:
shll-run generate-wallet only if user has no operator wallet.RUNNER_PRIVATE_KEY automatically for the current session after generating the wallet. Do not ask the user to set the environment variable manually.2. Verify gas:
3. If user has no token ID:
shll-run listings.recommended=true by default unless the user explicitly wants a specialized template.shll-run setup-guide -l -d .setupUrl plus the wallet-role explanation.4. User returns with token ID:
shll-run status -k .shll-run portfolio -k .status.readiness.ready, status.readiness.blockers, and status.readiness.nextActions as the primary onboarding diagnosis.Write Confirmation Policy
Before any write command, present:
Then wait for explicit user approval.
Write commands include:
swapwrapunwraptransferrawlendredeemfour_buyfour_sellRead-only commands (no confirmation needed): config, policies, status, history, portfolio, price, tokens, search, balance, four_info.
CLI Commands
Setup and account
shll-run generate-walletshll-run balanceshll-run listingsshll-run setup-guide [-l ] [-d ] shll-run init (disabled)If -l/--listing is omitted, setup-guide auto-selects an active listing from the indexer.
Trading and vault ops
shll-run swap -f -t -a -k shll-run wrap -a -k shll-run unwrap -a -k shll-run transfer --token -a --to -k shll-run raw --target --data -k Lending (Venus)
shll-run lend -t -a -k shll-run redeem -t -a -k Four.meme
shll-run four_info --token shll-run four_buy --token -a -k shll-run four_sell --token -a -k four_buy amount unit is BNB, not USD. If user gives a USD target, convert to BNB first and confirm the final BNB amount before execution.
Read-only and audit
shll-run config -k (view-only; modify via web console)shll-run portfolio -k shll-run price --token shll-run search --query shll-run tokensshll-run policies -k shll-run status -k shll-run history -k [--limit N] MCP Tools: Cross-skill Execution
For external aggregator calldata (OKX, 1inch, etc.):
1. Get quote/calldata from the external source. 2. Execute through SHLL MCP:
execute_calldataexecute_calldata_batchFor onboarding via MCP, setup_guide can auto-select an active listing when listing_id is omitted.
Security requirements:
1. Recipient must resolve to the vault address. 2. Undecodable recipient calldata is blocked. 3. Do not ask for unsafe bypass parameters.
Smart Routing Rule
When the user provides a token address:
1. Run four_info --token .
2. If tradingPhase is bonding curve, use four_buy / four_sell.
3. If tradingPhase is DEX or unsupported, use swap.
Common Errors and Fixes
1. RUNNER_PRIVATE_KEY environment variable is missing
RUNNER_PRIVATE_KEY automatically for the current session.RUNNER_PRIVATE_KEY manually and retry.2. NOT authorized for token-id
3. rental has EXPIRED or operator authorization has EXPIRED
4. status: error with errorCode: POLICY_REJECTED
details.reason and adjust limits, whitelists, cooldown, or policy config.5. Unable to decode recipient from calldata
6. No V2/V3 liquidity or direct path found
swap command handles native BNB automatically via swapExactETHForTokens. If a swap fails, it's because the direct pool is empty or invalid, not because BNB is unplugged.7. init command is disabled
setup-guide instead.8. Unsure what is broken
errorCode, message, and details fields in the JSON response first.Product UX Rules
1. Never describe generate-wallet as if it were the user's main wallet.
2. Always call it the operator wallet or AI hot wallet.
3. Always explain the dual-wallet model the first time setup is discussed.
4. Always warn that the operator wallet must not be used to mint, rent, or hold the Agent NFT.
5. Do not ask the user to manually set RUNNER_PRIVATE_KEY in OpenClaw; AI should do it.
6. After setup is complete and the user provides a token-id, run readiness checks automatically before asking the user what to do next.
7. When multiple listings are available, recommend one by default and explain why.
8. Prefer the structured status.readiness fields over ad-hoc prose when deciding the next user-facing instruction.
Redeploy Checklist
If AgentNFA, PolicyGuard, ListingManagerV2, or default listing changes:
1. Update constants in src/shared/constants.ts.
2. Validate ABIs if function signatures changed.
3. Rebuild:
npx tsc --noEmit
npm run build
4. Smoke test:
shll-run init still returns disabledExpected Output Format
All runtime responses should stay machine-friendly JSON:
{"status":"success", ...}{"status":"error","errorCode":"...", "message":"...", ...}Links
βοΈ Configuration
1. Install:
npm install -g shll-skills --registry https://registry.npmjs.org
2. Set operator private key:
export RUNNER_PRIVATE_KEY="0x..."
3. Optional - use a private RPC for better reliability and speed:
export SHLL_RPC="https://your-private-bsc-rpc.example.com"
4. Ensure operator wallet has small BNB balance for gas.