- name
- zl-claw-pay
- version
- 1.0.0
- description
- |
- author
- zlpay Team
- license
- MIT
- tags
- skill_type
- api
- execution_mode
- llm_driven
- has_server
- false
- has_install_scripts
- true
- requires
- security_level
- high
- environment_variables
- required
- optional
ZL Claw Pay Skill
ZL Pay Skill provides sub-wallet management, payment collection, and Token payment functions, building a dual-track payment system of "Fiat + Token".
Key Protocols
- Never expose credentials: Do not display API Key, Wallet ID or any sensitive information in chat responses.
- Explicit confirmation: Must ask for "yes/no" confirmation before executing payments.
*Format*: "I am about to send [amount] sat to [recipient/note]. Continue? (y/n)"
- Check balance first: Verify balance before payment to prevent errors.
- Always include QR code: When generating QR code: (a) display QR image, (b) output
MEDIA:+qr_filepath on same line. Never skip.
Execution Mode: LLM Driven
This Skill uses LLM-driven mode. The agent interacts with backend via command-line calls to skill.py.
Core Principles
- Stateless design: Each call starts a new process, exits immediately after execution
- Agent manages context: Session memory managed by agent, not dependent on local state
- Command-line driven: Execute all operations via
skill.pycommands - Dual command support:
callfor HTTP APIs and local interfaces
Command Format
# Unified calling method
python {baseDir}/scripts/skill.py call -interfaceId=<INTERFACE_ID> [--param1=value1] ...Command Design Principles:
- Unified command:
callfor all interface calls (HTTP and local) - Parameter passthrough: Control params via
-key=value, data params via--key=value - Auto authentication: Python code handles GM SM2/SM4 encryption and signing automatically
- Interface code: All calls must pass
-interfaceIdparameter
Interface Types
| Type | Code | Command | Description |
|---|---|---|---|
| HTTP API | C prefix | call | Requires network request to backend |
| Local Interface | L prefix | call | Direct local storage operation |
Documentation Guide
When processing user requests, consult documents in this order:
- Consult
references\api-spec.md: Get interface codes, trigger keywords, guidance phrases, request/response parameters - Consult
assets\ equest-examples.md: Get command-line calling examples - Execute command: Construct and execute commands according to documentation
CLI Command Examples
Local Interface (Query Binding Status):
python {baseDir}/scripts/skill.py call -interfaceId=L00001HTTP API (Generate QR Code):
python {baseDir}/scripts/skill.py call -interfaceId=C00004 --amount=100More examples in assets\
equest-examples.md.
Trigger Conditions
Activate when users need to handle payment-related business:
- Query binding status: User asks "Have I bound my wallet", "Query sub-wallet"
- Bind sub-wallet: User says "Bind wallet", "Open account", "Create wallet"
- Collect payment: User says "Generate QR code", "Collect money", "Receive payment"
- Query payment status: User asks "Payment successful", "Check order status"
- Query balance: User says "Check balance", "How much money left"
- Query transactions: User says "Transaction records", "Bill", "Collection details"
Not applicable for: non-payment scenarios, batch operations, historical data export.
Execution Steps
- Consult interface documentation: Based on user intent, consult
references\api-spec.mdfor interface codes and parameters - Consult calling examples: Get command format from
assets\ equest-examples.md - Construct command: Use
callcommand:
- Local interface (L prefix): call -interfaceId=L00001 - HTTP interface (C prefix): call -interfaceId=C00003
- Execute command: Run the constructed command
- Parse response: Process JSON response, extract
success,data,_seq_idfields - Generate reply: Create user-friendly response based on result
Output Format
Success Response:
[Operation success description]
[Related business data display]Failure Response:
[Error description]
[Suggested action]QR Code Response (Must include):
Please scan the QR code to complete [amount] collection:
MEDIA:[QR code file path]Security Protocols
- Never expose credentials: Do not display API Key, Wallet ID or sensitive info
- Explicit confirmation: Must ask "yes/no" confirmation before payment
- Pre-payment confirmation format: "I am about to [operation description]. Continue? (y/n)"
- Sensitive info management: All sensitive info managed by OpenClaw Memory system
Detailed security specs in "Sensitive Information Management" section of references\api-spec.md.
Business Scenarios and Interface Mapping
| Scenario | Interface Code | Reference Document |
|---|---|---|
| Query binding status | L00001 | references\api-spec.md |
| Bind sub-wallet | C00003 | references\api-spec.md |
| Generate QR code | C00004 | references\api-spec.md |
| Query payment status | C00005 | references\api-spec.md |
| Query balance | C00006 | references\api-spec.md |
Document Index
| Document | Content |
|---|---|
references\api-spec.md | Interface list, trigger keywords, guidance phrases, request/response parameters |
assets\
equest-examples.md | Command-line calling examples |
Account System
Account Types
- Host Wallet: Payment account, supports deposit, withdrawal, trading, settlement
- Sub-wallet: Collection account, funds aggregated to host wallet
- Token Account: Lobster ecosystem account for in-ecosystem transactions
Usage Scenarios
- Full form: Sub-wallet + Token account, supports full-featured payments
- Traditional e-commerce: Sub-wallet only, fiat collection and settlement
- Pure AI compute: Token account only, in-ecosystem consumption and settlement
Security Notes
Transport Security
- Mandatory HTTPS/TLS 1.3 encryption
- GM SM2/SM4: Request body encrypted with SM4, key encrypted with SM2
- SM2 digital signature: Request and response use SM2 signature verification
- Anti-replay: Timestamp + Nonce
- Response verification: Verify server SM2 signature
Credential Management
API Key
- Source: Multiple input methods (in priority order):
1. Command line argument: -api-key=xxx 2. Request body parameter: api_key (e.g., bind_sub_wallet) 3. Environment variable: ZLPAY_API_KEY 4. Memory storage: saved after successful bind_sub_wallet
- Storage: Optionally saved to memory after bind_sub_wallet, not written to config files
- Display: Never show full API Key in conversation, only show first 8 and last 4 digits
- Security: Use IronClaw Data Guard to check output, prevent credential leakage
Wallet ID
- Source: Provided by user during chat interaction
- Storage: Saved to local state file (
~/.zlpay/state.json) - Usage: Auto-retrieved from state file on subsequent API calls
- Display: Never show full wallet ID in chat (mask as
wallet_****5678)
Configuration Parameters (GM Keys, App ID, API URL, Encryption)
- Source: Configured in
config/.envfile - Required:
ZLPAY_APP_ID,ZLPAY_GM_CLIENT_PRIVATE_KEY,ZLPAY_GM_SERVER_PUBLIC_KEY,ZLPAY_API_URL - Optional:
ZLPAY_GM_ENABLE_ENCRYPTION(default: true) - Alternative: Can use file paths (
*_PATHvariants) for key files with 600 permissions - Security: Keys are only used for request signing/verification, never transmitted over network
Data Masking
Sensitive info in responses is automatically masked:
- Phone:
138****8000 - ID Number:
110101********1234
Configuration
All settings are stored in config/.env:
- Required:
ZLPAY_APP_ID,ZLPAY_GM_CLIENT_PRIVATE_KEY,ZLPAY_GM_SERVER_PUBLIC_KEY - Optional:
ZLPAY_API_URL,ZLPAY_LOG_LEVEL
API Key: User provides during chat (stored in OpenClaw Memory, not in config file)
Local Files: Creates ~/.zlpay/ directory for state storage and logs (user-only permissions).