wallet

💰 钱包技能

支持多链的钱包，涵盖 EVM（DeBank 支持的链）和 Solana。支持余额查询、 转账、签名和策略管理。脚本技能——通过 bash 调用下方函数；不会注册钱包工具。

调用方法

所有读取／转账／签名操作都是 core.skill_tools.wallet 中的 Python 函数。 通过 bash 运行并读取 JSON 结果：

python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_balance(chain='base')))"

唯一一个不是脚本函数的操作是提议钱包策略 ——此操作需要在 UI 中呈现确认卡片，因此需通过原生的 frontend_action 工具执行（参见下方的策略管理）。

函数（from core.skill_tools import wallet）

函数	说明
wallet_info()	获取所有 AGENT 钱包地址
get_user_wallets()	用户自己的钱包（登录钱包 + 次要钱包）——只读，来自环境变量
wallet_balance(chain, address="", asset="")	查询某条 EVM 链上的余额（DeBank）。必须指定 chain
wallet_sol_balance(address="", asset="")	查询 Solana 余额（Birdeye）
wallet_get_all_balances(evm_address="", sol_address="")	一次查询所有链的余额
wallet_transfer(to, amount, chain_id=1, data="", **kw)	广播 EVM 交易（默认由平台赞助 gas）
wallet_sign_transaction(to, amount, chain_id=1, data="", **kw)	签署 EVM 交易（不广播）
wallet_sign(message)	EIP-191 消息签名
wallet_sign_typed_data(domain, types, primaryType, message)	EIP-712 类型化数据签名
wallet_transactions(chain="ethereum", asset="", limit=20)	EVM 交易历史
wallet_sol_transfer(transaction, caip2=...)	广播 Solana 交易（base64）
wallet_sol_sign_transaction(transaction)	签署 Solana 交易（不广播）
wallet_sol_sign(message)	Solana 消息签名
wallet_sol_transactions(chain="solana", asset="sol", limit=20)	Solana 交易历史
wallet_get_policy(chain_type="ethereum")	检查策略状态
validate_and_clean_rules(rules, chain_type)	提议策略前预先验证策略规则

用户自己的钱包（登录钱包／次要钱包）

Agent 钱包不是用户的钱包。平台会将用户自己的钱包身份作为环境变量注入 （在容器启动时以及用户执行钱包操作时从控制平面同步）：

• USER_LOGIN_WALLET_ADDRESS / USER_LOGIN_WALLET_TYPE ——用户登录时使用的钱包 （或绑定为主钱包的钱包）。
• USER_SECONDARY_WALLET_ADDRESS / USER_SECONDARY_WALLET_TYPE ——用户关联的 另一个钱包（例如，登录钱包是 EVM 钱包时的 Solana 钱包）。

当用户询问“我的钱包是什么”／“我的登录钱包”／“查看我的余额”时，读取 这些变量——不要回答 Agent 钱包，也不要说你不知道：

python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.get_user_wallets()))"

值为空或缺失，表示用户从未在该位置绑定钱包 （例如使用社交账号登录）——请说明这一点，并引导用户在 Web 应用中绑定钱包。

规则：

• 只读。 Agent 不持有这些钱包的密钥。若要查询用户的余额，请将地址传入 wallet_balance(chain, address=...) / wallet_sol_balance(address=...)。
• 用户钱包发起的交易绝不通过脚本函数执行——请使用原生的 frontend_action(action_type="user_wallet_tx", ...) 流程， 由用户在 UI 中签名，并在服务端强制校验 expected_from。

关键事实

• EVM 的金额单位为 wei（用于 wallet_transfer / wallet_sign_transaction）。0.01 ETH = 10000000000000000。发送 ERC-20 代币时，amount 为 0（原生代币），转账信息会编码在 data calldata 中。
• 默认由赞助方支付 Gas，适用于 EVM 链——用户无需持有原生代币来支付 Gas。若不可用，则改由用户支付。传入 sponsor=False 可从钱包余额中支付 Gas。
• 策略默认处于关闭状态（允许所有操作）。仅启用策略时，交易才需要 UI 确认。
• 支持的 EVM 链：所有 DeBank 支持的链。常见名称会自动映射（例如，avalanche → avax、bsc → bsc、zksync → era）。备用别名包括 ethereum/base/arbitrum/optimism/polygon/linea/bsc/avalanche/fantom/gnosis/zksync/scroll/blast/mantle/celo/aurora，以及 monad/world/unichain/abstract/sonic/berachain。
• 余额来源：DeBank（EVM）、Birdeye（Solana）、wallet-service（备用来源）。sc-proxy 会自动注入 DeBank/Birdeye 密钥。

工作流

检查余额

python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_balance(chain='base')))"
python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_get_all_balances()))"

发送交易（EVM）

务必在交易前验证余额，并在交易后检查结果/历史记录。

# 1. check
python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_balance(chain='base')))"
# 2. transfer (amount in wei)
python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_transfer(to='0x...', amount='10000000000000000', chain_id=8453)))"
# 3. verify
python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_transactions(chain='base')))"

签署 EIP-712 类型化数据

python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_sign_typed_data(domain={...}, types={...}, primaryType='Permit', message={...})))"

策略管理

检查策略是脚本函数；提议策略则使用原生的 frontend_action 工具（该工具会在 UI 中呈现签名卡片，脚本无法做到这一点）。

1. 检查当前策略：

   python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.wallet_get_policy(chain_type='ethereum')))"
   

2. （可选）预先验证规则：

   python3 -c "from core.skill_tools import wallet; import json; print(json.dumps(wallet.validate_and_clean_rules([...], 'ethereum')))"
   

3. 提议策略——调用 frontend_action 工具（而非脚本）：

   frontend_action(action_type="update_wallet_policy", chain_type="ethereum", rules=[...])
   

   用户会在 UI 中确认并签名。每条链调用一次（EVM + Solana = 调用两次）。

标准通配符策略（需要时）

rules = [
  {"name": "Deny key export", "method": "exportPrivateKey", "conditions": [], "action": "DENY"},
  {"name": "Allow all", "method": "*", "conditions": [], "action": "ALLOW"},
]

策略模式 — 关键决策表

⚠️ 在 Privy 中，DENY 优先于 ALLOW。 DENY * 会覆盖所有 ALLOW 规则。切勿混用。

模式	规则	效果
允许所有（默认）	DENY exportPrivateKey + ALLOW *	除导出密钥外，允许所有操作
全部拒绝（锁定）	DENY exportPrivateKey + DENY *	无法执行任何操作。不要设置 ALLOW 规则！
白名单（选择性允许）	DENY exportPrivateKey + 仅包含特定的 ALLOW 规则	仅允许白名单中的操作，其余操作均默认拒绝

模式 1：允许所有（标准通配符）

rules = [
  {"name": "Deny key export", "method": "exportPrivateKey", "conditions": [], "action": "DENY"},
  {"name": "Allow all", "method": "*", "conditions": [], "action": "ALLOW"},
]

模式 2：全部拒绝（锁定）

rules = [
  {"name": "Deny key export", "method": "exportPrivateKey", "conditions": [], "action": "DENY"},
  {"name": "Deny all actions", "method": "*", "conditions": [], "action": "DENY"},
]
# ⚠️ NO ALLOW rules here — DENY * would override them!

模式 3：白名单（选择性允许）

rules = [
  {"name": "Deny key export", "method": "exportPrivateKey", "conditions": [], "action": "DENY"},
  {"name": "Allow transfer to Uniswap", "method": "eth_sendTransaction", "conditions": [
    {"field_source": "ethereum_transaction", "field": "to", "operator": "eq", "value": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"}
  ], "action": "ALLOW"},
]
# ⚠️ NO "DENY *" here! enabled=true already denies everything not ALLOWed.
# Adding DENY * would override the ALLOW rules above (DENY > ALLOW).

Privy 策略规则 — 关键限制

规则	详情
默认行为	enabled=true → 除非明确设为 ALLOW，否则全部拒绝
DENY > ALLOW	两者同时匹配时，DENY 始终优先
空条件	只有 exportPrivateKey 和 *（通配符）允许 conditions: []
TX 方法需要条件	eth_sendTransaction、eth_signTransaction、eth_signTypedData_v4、eth_signUserOperation、signAndSendTransaction 等，全部至少需要 1 个条件
有效的 field_sources	EVM：ethereum_transaction（to/value/chain_id）、ethereum_calldata（function_name）、ethereum_typed_data_domain（chainId/verifyingContract）、ethereum_typed_data_message、system
有效运算符	eq、gt、gte、lt、lte、in（数组，最多 100 个值）
双链	EVM + Solana 需要调用两次 frontend_action(action_type="update_wallet_policy", ...)

注意事项

• 策略提议通过 frontend_action 工具进行——需要活动的 SSE 会话（无法从后台任务调用）。
• wallet_balance 需要指定 chain——使用 wallet_get_all_balances 来发现链。
• 若要同时设置 EVM + Solana 策略，需调用两次 frontend_action（每种 chain_type 各一次）。