openclaw-master-skills/skills/upload-clawhub

SHLL Skills — AI Agent DeFi Toolkit on BSC

A CLI + MCP Server toolkit that gives any AI agent the ability to execute DeFi operations on BSC Mainnet securely. Supports PancakeSwap V2/V3 swaps, Venus lending, Four.meme bonding curve trades, setup flows, and raw calldata execution through PolicyGuard.

Version 6.0.0 finalizes the modular layout:

• shared/* for constants, clients, schemas, errors, ABIs, and cross-cutting helpers
• services/* for single-source business logic
• commands/* and tools/* as thin CLI/MCP adapters

Install

npm install -g shll-skills

This installs two binaries:

• shll-run — CLI mode (for OpenClaw, shell scripts, etc.)
• shll-mcp — MCP Server mode (for Claude, Cursor, Gemini, etc.)

---

🔌 MCP Server Setup (Recommended for AI Agents)

The Model Context Protocol lets AI agents discover and call SHLL tools natively — no CLI parsing needed.

Security: RUNNER_PRIVATE_KEY must be a dedicated operator hot wallet with minimal BNB (~) for gas only. Generate one with shll-run generate-wallet. Never use your main wallet or any wallet holding significant funds. Even if this key is compromised, on-chain PolicyGuard limits the operator to policy-approved trades only it cannot withdraw vault funds or transfer the Agent NFT.

Claude Desktop

Edit ~/AppData/Roaming/Claude/claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "shll-defi": {
      "command": "shll-mcp",
      "env": {
        "RUNNER_PRIVATE_KEY": "0x_YOUR_OPERATOR_PRIVATE_KEY"
      }
    }
  }
}

Restart Claude Desktop. You'll see SHLL tools appear in the 🔧 menu.

Cursor

Create .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "shll-defi": {
      "command": "npx",
      "args": ["-y", "shll-skills", "--mcp"],
      "env": {
        "RUNNER_PRIVATE_KEY": "0x_YOUR_OPERATOR_PRIVATE_KEY"
      }
    }
  }
}

Custom Agent (programmatic)

RUNNER_PRIVATE_KEY=0x... shll-mcp

The server communicates via stdio using JSON-RPC 2.0. Send tools/list to discover all available tools.

Available MCP Tools (24 total)

Tool	Type	Description
portfolio	Read	Vault holdings + token balances
balance	Read	BNB or token balance of the agent vault
price	Read	Real-time token price (DexScreener)
search	Read	Search token by name/symbol on BSC
tokens	Read	List known token symbols + addresses
policies	Read	View active on-chain policies + config
status	Read	One-shot readiness overview with blockers, warnings, and next actions
history	Read	Recent transactions + policy rejections
token_restriction	Read	View token whitelist restriction status + whitelisted tokens
listings	Read	Available agent templates for subscription
four_info	Read	Query Four.meme bonding curve token info
swap	Write	PancakeSwap V2/V3 auto-routing swap
wrap	Write	BNB → WBNB in vault
unwrap	Write	WBNB → BNB in vault
lend	Write	Supply tokens to Venus for yield
redeem	Write	Withdraw from Venus
transfer	Write	Send BNB or ERC20 from vault
four_buy	Write	Buy a Four.meme bonding-curve token
four_sell	Write	Sell a Four.meme bonding-curve token
config	Write	Configure risk parameters (spending limits, cooldown)
setup_guide	Info	Generate dual-wallet onboarding URL + steps
generate_wallet	Info	Create new operator wallet (not the owner, mint, or vault wallet)
execute_calldata	Write	Execute raw calldata from any source through PolicyGuard
execute_calldata_batch	Write	Execute multiple calldata actions atomically through PolicyGuard

---

📟 CLI Mode

For OpenClaw, shell scripts, or manual use.

Quick Start

# 1. Generate an operator wallet (AI-only hot wallet)
shll-run generate-wallet
export RUNNER_PRIVATE_KEY="0x..."

# 2. Get setup link (user completes on shll.run with their OWNER wallet)
shll-run setup-guide -l 0xABC...DEF -d 30

# 3. After the user sends back token-id, verify readiness
shll-run status -k 5
shll-run portfolio -k 5

# 4. Trade
shll-run swap -f BNB -t USDC -a 0.1 -k 5

In OpenClaw, AI should set RUNNER_PRIVATE_KEY for the current session automatically. Do not ask the user to edit environment variables manually during chat onboarding.

Commands

Trading

shll-run swap -f <FROM> -t <TO> -a <AMT> -k <ID>              # Auto V2/V3 routing
shll-run swap -f BNB -t USDT -a 0.1 -k 5 -v v3 -s 2           # Use V3 with 2% slippage
shll-run wrap -a <BNB> -k <ID>                                # BNB -> WBNB
shll-run unwrap -a <BNB> -k <ID>                              # WBNB -> BNB
shll-run transfer --token <SYM> -a <AMT> --to <ADDR> -k <ID>
shll-run four_buy --token <ADDR> -a <BNB> -k <ID>            # Buy on Four.meme bonding curve
shll-run four_sell --token <ADDR> -a <TOKEN_AMT> -k <ID>     # Sell on Four.meme bonding curve

Lending (Venus Protocol)

shll-run lend -t USDT -a 100 -k <ID>      # Supply to Venus
shll-run redeem -t USDT -a 50 -k <ID>     # Withdraw from Venus

Market Data (read-only)

shll-run portfolio -k <ID>        # Vault holdings + USD values
shll-run price --token <SYM>      # Real-time price (DexScreener)
shll-run search --query <TEXT>     # Find token by name
shll-run tokens                   # List known tokens
shll-run four_info --token <ADDR> # Four.meme token status

Risk Management

shll-run policies -k <ID>         # View active on-chain policies
shll-run status -k <ID>           # Readiness, blockers, warnings, next actions
shll-run config -k <ID> --tx-limit <BNB> --daily-limit <BNB> --cooldown <SEC>

---

How It Works

AI Agent -> CLI/MCP -> PolicyClient.validate() -> PolicyGuard (on-chain) -> vault

1. AI constructs a tool call (MCP) or CLI command
2. PolicyClient.validate() simulates against all on-chain policies
3. If approved, AgentNFA.execute() routes through PolicyGuard → vault
4. PolicyGuard enforces: spending limits, cooldowns, recipient checks, and protocol rules

Security: Dual-Wallet Architecture

	Owner Wallet	Operator Wallet (RUNNER_PRIVATE_KEY)
Who holds it	User (MetaMask/hardware)	AI agent
Use it for	Subscribe or mint the agent, hold the Agent NFT, authorize operator	Pay gas and execute policy-limited actions
Can trade	—	✅ Within PolicyGuard limits
Can withdraw vault	✅	❌
Can transfer NFT	✅	❌
Risk if leaked	🚨 Full vault access	⚠️ Limited to policy-allowed trades

Do not use the operator wallet to mint or subscribe to the agent. Do not hold the Agent NFT in the operator wallet. Keep only a small BNB balance there for gas.

After setup, run status first. It returns a machine-friendly readiness object with:

• readiness.ready
• readiness.blockers
• readiness.warnings
• readiness.nextActions

This is the intended handoff for AI onboarding flows before any trading command.

Environment Variables

Variable	Required	Description
RUNNER_PRIVATE_KEY	Yes for write ops and agent-linked reads	Operator wallet key (~$1 BNB for gas)
SHLL_RPC	No	BSC RPC URL override. Recommended: use a private RPC (e.g. QuickNode, Alchemy, GetBlock) for better reliability and speed

Note: Contract addresses (AgentNFA, PolicyGuard) are hardcoded for security reasons. Override env vars are intentionally not supported to prevent supply-chain attacks.

Links

• Website: shll.run
• Twitter: @shllrun
• npm: shll-skills
• GitHub: kledx/shll-skills

🧩 Multi-Skill Compatibility

SHLL can coexist with other DeFi skills (OKX DEX API, Bitget Wallet, etc.). Key architectural differences:

	SHLL	OKX DEX API	Bitget Wallet
Wallet	Smart contract vault (AgentNFA)	User EOA	Bitget custody
Execution	On-chain via PolicyGuard	Calldata only (user signs)	HMAC API
Safety	On-chain policy enforcement	User approval	API key perms
AI autonomy	Execute within policy limits	Cannot execute	Full API access
Risk if key leaked	Policy-limited trades only	N/A	Full API access

SHLL is the only skill with on-chain policy enforcement. Even if the AI hallucinates, the smart contract rejects unsafe operations.

License

MIT