zl-clawpay（zl 爪支付）

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

1. Never expose credentials: Do not display API Key, Wallet ID or any sensitive information in chat responses.
2. 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)"

1. Check balance first: Verify balance before payment to prevent errors.
2. Always include QR code: When generating QR code: (a) display QR image, (b) output MEDIA: + qr_file path 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.py commands
• Dual command support: call for 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: call for 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 -interfaceId parameter

Interface Types

Documentation Guide

When processing user requests, consult documents in this order:

1. Consult references\api-spec.md: Get interface codes, trigger keywords, guidance phrases, request/response parameters
2. Consult assets\ equest-examples.md: Get command-line calling examples
3. Execute command: Construct and execute commands according to documentation

CLI Command Examples

Local Interface (Query Binding Status):

python {baseDir}/scripts/skill.py call -interfaceId=L00001

HTTP API (Generate QR Code):

python {baseDir}/scripts/skill.py call -interfaceId=C00004 --amount=100

More 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

1. Consult interface documentation: Based on user intent, consult references\api-spec.md for interface codes and parameters
2. Consult calling examples: Get command format from assets\ equest-examples.md
3. Construct command: Use call command:

- Local interface (L prefix): call -interfaceId=L00001 - HTTP interface (C prefix): call -interfaceId=C00003

1. Execute command: Run the constructed command
2. Parse response: Process JSON response, extract success, data, _seq_id fields
3. 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

1. Never expose credentials: Do not display API Key, Wallet ID or sensitive info
2. Explicit confirmation: Must ask "yes/no" confirmation before payment
3. Pre-payment confirmation format: "I am about to [operation description]. Continue? (y/n)"
4. 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

Document Index

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/.env file
• 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 (*_PATH variants) 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).