wallet-policy

Q: How do I install wallet-policy?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill wallet-policy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/wallet-policy/ (personal) or .claude/skills/wallet-policy/ (project).

by starchild-ai-agentAI & Agents

Generate Privy wallet policy rules from natural language. Use when the user wants to set up, modify, or review wallet security policies — transfer limits, address allowlists, method restrictions, time windows, etc.

Installs: 4.1K
Last 24h: —
Trending rank: —
Security: Warn

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/starchild-ai-agent/official-skills --skill wallet-policy

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads wallet-policy automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

Security audits

Independent scans of the skill's instructions and bundled files.

Gen Agent Trust Hub PassSAFE ·This skill is a utility for generating and proposing blockchain wallet security policies via the Privy API. It uses natural language processing to construct policy JSONs and invokes a specific tool for user review and approval, incorporating standard security practices like denying private key exports by default.

Socket PassNo alerts

Snyk WarnMEDIUM ·Risk: MEDIUM · 1 issue

Runlayer PassLOW ·1/1 file flagged

SKILL.md

The instructions your agent reads when the skill is triggered.

Wallet Policy Generator

You help users create wallet security policy rules. The user describes what they want in plain language, and you generate the exact Privy policy rules JSON. After generating the rules, you MUST call the wallet_propose_policy tool to send the proposal to the user for review and approval.

Always respond in the user's language.

Output Format

After generating the policy rules, call the wallet_propose_policy tool:

wallet_propose_policy(
  chain_type="ethereum",          # "ethereum" or "solana"
  title="Update EVM Wallet Policy",
  description="Allow transfers to treasury address",
  rules=[
    {
      "name": "Allow transfers to treasury",
      "method": "eth_sendTransaction",
      "conditions": [
        {
          "field_source": "ethereum_transaction",
          "field": "to",
          "operator": "eq",
          "value": "0x1234567890abcdef1234567890abcdef12345678"
        }
      ],
      "action": "ALLOW"
    }
  ]
)

The tool sends an action_request event to the frontend, which displays the proposed policy to the user for confirmation. The user must approve (and sign) before the policy is applied. Do NOT output rules as code blocks — always use the tool.

If the user's request covers both EVM and Solana, call wallet_propose_policy twice — once with chain_type="ethereum" and once with chain_type="solana".

CRITICAL — Tool invocation is mandatory:

You MUST call wallet_propose_policy for EVERY policy request. Never output rules as plain text or code blocks.
For dual-chain requests (both EVM and Solana), call the tool TWICE — once per chain_type.
The tool validates rules against the Privy API schema. If validation fails, fix the errors and retry.

Policy Engine Basics

Tell the user these fundamentals when relevant:

Default allow-all — New wallets have NO policy (all transactions allowed). Policy is opt-in. Once a policy is attached, it switches to deny-by-default: any request that matches no rules is denied. An empty rules array = deny everything.
DENY wins — If any DENY rule matches, the request is blocked even if ALLOW rules also match.
Multiple conditions = AND — All conditions in a single rule must match for the rule to trigger.
Multiple rules = evaluated in order — First matching DENY blocks; otherwise first matching ALLOW permits.
Solana per-instruction — Every instruction in a Solana transaction must individually match an ALLOW rule.

Constructing Policy Rules

Default Approach: Wildcard Policy

For any on-chain service (Hyperliquid, Orderly, 1inch, or any new dapp), propose the standard wildcard policy:

wallet_propose_policy(
  chain_type="ethereum",
  title="Enable Wallet Operations",
  description="Allows all transactions and signing on all EVM chains. Only blocks private key export. The user signs each individual transaction for approval.",
  rules=[
    {
      "name": "Deny key export",
      "method": "exportPrivateKey",
      "conditions": [],
      "action": "DENY"
    },
    {
      "name": "Allow all operations",
      "method": "*",
      "conditions": [],
      "action": "ALLOW"
    }
  ]
)

This works because:

The wallet policy acts as a capability gate — the user's signature on the policy is explicit consent to enable on-chain operations
Individual transactions still require user approval in the frontend before execution
The DENY on exportPrivateKey prevents the most dangerous operation (key extraction)
The * wildcard covers all transaction types, signing methods, and chains — no service-specific rules needed

When to use specific rules instead: Only when the user explicitly requests tighter restrictions (e.g. "only allow transfers under 1 ETH", "only allow transactions on Arbitrum", "only allow this specific contract address"). In that case, use the rule-building reference below.

Building Custom Restrictive Rules

If the user wants tighter control, identify what transactions the service needs:

What contract addresses will be called? (the to field)
What chain will it operate on? (the chain_id)
What value will be sent? (native token amount in wei)
Does it need EIP-712 signing? (typed data for off-chain orders, permits)
Does it need token approvals? (ERC-20 approve calls to token contracts)

Map each transaction type to a policy rule:

Transaction type	Rule pattern
Call a specific contract	`ethereum_transaction.to` = contract address + `chain_id` = chain
ERC-20 token approval	`ethereum_transaction.value` = "0" + `chain_id` = chain (approvals are zero-value calls to the token contract)
EIP-712 typed data signing	`ethereum_typed_data_domain.verifyingContract` = contract address
Any transaction on a chain	`ethereum_transaction.chain_id` = chain
Smart contract deployment	Use wildcard pattern (deployments have no fixed `to` address)

Propose and Explain

Always use wallet_propose_policy to send the proposal to the user. In the description field, explain:

What the rules allow
What security tradeoffs exist (e.g. wildcard allows all operations, but each tx still requires user approval)

Complete Rule Schema

{
  "name": "string (1-50 chars, descriptive)",
  "method": "<method>",
  "conditions": [ <condition>, ... ],
  "action": "ALLOW" | "DENY"
}

Supported Methods

Method	Chain	Description
`eth_sendTransaction`	EVM	Broadcast a transaction
`eth_signTransaction`	EVM	Sign without broadcasting
`eth_signTypedData_v4`	EVM	Sign EIP-712 typed data
`eth_signUserOperation`	EVM	Sign ERC-4337 UserOperation
`eth_sign7702Authorization`	EVM	EIP-7702 authorization
`signTransaction`	Solana	Sign a Solana transaction
`signAndSendTransaction`	Solana	Sign and broadcast
`signTransactionBytes`	Tron/SUI	Sign raw transaction bytes
`exportPrivateKey`	Any	Export the private key
`*`	Any	Wildcard — matches all methods

Note: personal_sign (message signing) and signMessage (Solana) are NOT valid policy methods. They cannot be individually allowed/denied. To allow message signing, use * wildcard. Under deny-all (empty rules), message signing is also blocked.

Condition Object

{
  "field_source": "<source>",
  "field": "<field_name>",
  "operator": "<op>",
  "value": "<string>" | ["<string>", ...]
}

Operators:

eq — equals (single value)
gt, gte, lt, lte — comparison operators (numeric string values)
in — matches any value in array (max 100 values). Use this for multiple addresses/values.

Do NOT use in_condition_set:

in_condition_set — This operator requires pre-created condition sets via Privy API, which you cannot create. Always use the in operator instead for arrays of addresses or values. If you need more than 100 values, split into multiple rules.

Examples:

// ✅ CORRECT: Multiple addresses with "in" operator
{"field": "to", "operator": "in", "value": ["0xAddr1...", "0xAddr2...", "0xAddr3..."]}

// ❌ WRONG: Do NOT use "in_condition_set" - you cannot create condition sets
{"field": "to", "operator": "in_condition_set", "value": "a2p4etpcbj2dltbjfigybi8j"}
{"field": "to", "operator": "in_condition_set", "value": ["0xAddr1...", "0xAddr2..."]}

// ✅ CORRECT: For many addresses, use multiple rules with "in" operator
// Rule 1: First 100 addresses
{"field": "to", "operator": "in", "value": ["0xAddr1...", "0xAddr2...", /* ... 100 addresses */]}
// Rule 2: Next batch
{"field": "to", "operator": "in", "value": ["0xAddr101...", "0xAddr102...", /* ... */]}

Condition Types Reference

1. `ethereum_transaction`

Fields: to, value, chain_id

{"field_source": "ethereum_transaction", "field": "to", "operator": "eq", "value": "0xAbC..."}
{"field_source": "ethereum_transaction", "field": "value", "operator": "lte", "value": "1000000000000000000"}
{"field_source": "ethereum_transaction", "field": "chain_id", "operator": "in", "value": ["1", "8453", "10"]}

value is in wei (string). 1 ETH = "1000000000000000000"
chain_id is string (e.g. "1" for mainnet, "8453" for Base)
to is checksummed address

2. `ethereum_calldata`

For decoded smart contract calls. Requires an abi field.

{
  "field_source": "ethereum_calldata",
  "field": "transfer.to",
  "operator": "eq",
  "value": "0xRecipient...",
  "abi": {
    "type": "function",
    "name": "transfer",
    "inputs": [
      {"name": "to", "type": "address"},
      {"name": "amount", "type": "uint256"}
    ]
  }
}

Field format: <functionName>.<paramName> — references decoded parameter.

3. `ethereum_typed_data_domain`

Fields: chainId, verifyingContract

{"field_source": "ethereum_typed_data_domain", "field": "verifyingContract", "operator": "eq", "value": "0xContract..."}
{"field_source": "ethereum_typed_data_domain", "field": "chainId", "operator": "eq", "value": "1"}

4. `ethereum_typed_data_message`

For EIP-712 message fields. Requires a typed_data descriptor.

{
  "field_source": "ethereum_typed_data_message",
  "field": "spender",
  "operator": "eq",
  "value": "0xSpender...",
  "typed_data": {
    "types": {
      "Permit": [
        {"name": "owner", "type": "address"},
        {"name": "spender", "type": "address"},
        {"name": "value", "type": "uint256"}
      ]
    },
    "primary_type": "Permit"
  }
}

5. `ethereum_7702_authorization`

Field: contract

{"field_source": "ethereum_7702_authorization", "field": "contract", "operator": "in", "value": ["0xA...", "0xB..."]}

6. `solana_program_instruction`

Field: programId

{"field_source": "solana_program_instruction", "field": "programId", "operator": "eq", "value": "11111111111111111111111111111111"}
{"field_source": "solana_program_instruction", "field": "programId", "operator": "in", "value": ["11111111111111111111111111111111", "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"]}

7. `solana_system_program_instruction`

Fields: instructionName, Transfer.from, Transfer.to, Transfer.lamports

{"field_source": "solana_system_program_instruction", "field": "instructionName", "operator": "eq", "value": "Transfer"}
{"field_source": "solana_system_program_instruction", "field": "Transfer.to", "operator": "eq", "value": "RecipientPubkey..."}
{"field_source": "solana_system_program_instruction", "field": "Transfer.lamports", "operator": "lte", "value": "1000000000"}

lamports is string. 1 SOL = "1000000000" (10^9)

8. `solana_token_program_instruction`

Fields: instructionName, TransferChecked.source, TransferChecked.destination, TransferChecked.authority, TransferChecked.amount, TransferChecked.mint

{"field_source": "solana_token_program_instruction", "field": "instructionName", "operator": "eq", "value": "TransferChecked"}
{"field_source": "solana_token_program_instruction", "field": "TransferChecked.mint", "operator": "eq", "value": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"}
{"field_source": "solana_token_program_instruction", "field": "TransferChecked.amount", "operator": "lte", "value": "1000000"}

9. `system`

Field: current_unix_timestamp

{"field_source": "system", "field": "current_unix_timestamp", "operator": "lte", "value": "1735689600"}

Use for time-bounded policies (e.g. "allow transfers until 2025-01-01").

Common Policy Recipes

Use these as building blocks. Combine multiple conditions in one rule for AND logic. Use separate rules for OR logic.

EVM: Address Allowlist

Allow sending only to specific addresses:

{
  "name": "Allowlist recipients",
  "method": "eth_sendTransaction",
  "conditions": [
    {"field_source": "ethereum_transaction", "field": "to", "operator": "in", "value": ["0xAddr1...", "0xAddr2..."]}
  ],
  "action": "ALLOW"
}

EVM: Transfer Value Cap

Allow transfers up to 0.1 ETH:

{
  "name": "Max 0.1 ETH per tx",
  "method": "eth_sendTransaction",
  "conditions": [
    {"field_source": "ethereum_transaction", "field": "value", "operator": "lte", "value": "100000000000000000"}
  ],
  "action": "ALLOW"
}

EVM: Chain Restriction

Allow only on Base and Ethereum mainnet:

{
  "name": "Base and mainnet only",
  "method": "eth_sendTransaction",
  "conditions": [
    {"field_source": "ethereum_transaction", "field": "chain_id", "operator": "in", "value": ["1", "8453"]}
  ],
  "action": "ALLOW"
}

EVM: Combined — Allowlist + Cap + Chain

{
  "name": "Treasury transfers on Base, max 1 ETH",
  "method": "eth_sendTransaction",
  "conditions": [
    {"field_source": "ethereum_transaction", "field": "to", "operator": "eq", "value": "0xTreasury..."},
    {"field_source": "ethereum_transaction", "field": "value", "operator": "lte", "value": "1000000000000000000"},
    {"field_source": "ethereum_transaction", "field": "chain_id", "operator": "eq", "value": "8453"}
  ],
  "action": "ALLOW"
}

Allow All Operations (including message signing)

personal_sign and signMessage are not valid policy methods. Use * wildcard to allow them. Combine with specific DENY rules to restrict dangerous operations.

{
  "name": "Allow all operations",
  "method": "*",
  "conditions": [],
  "action": "ALLOW"
}

Typical pattern: DENY dangerous methods first, then ALLOW * for the rest:

[
  {"name": "Block key export", "method": "exportPrivateKey", "conditions": [], "action": "DENY"},
  {"name": "Allow everything else", "method": "*", "conditions": [], "action": "ALLOW"}
]

EVM: USDC Contract on Base

{
  "name": "Allow USDC on Base",
  "method": "eth_sendTransaction",
  "conditions": [
    {"field_source": "ethereum_transaction", "field": "to", "operator": "eq", "value": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913"},
    {"field_source": "ethereum_transaction", "field": "chain_id", "operator": "eq", "value": "8453"}
  ],
  "action": "ALLOW"
}

EVM: Block Private Key Export

{
  "name": "Never export private key",
  "method": "exportPrivateKey",
  "conditions": [],
  "action": "DENY"
}

EVM: Time-Bounded Access

Allow transfers until a specific date:

{
  "name": "Allow until 2025-06-01",
  "method": "eth_sendTransaction",
  "conditions": [
    {"field_source": "system", "field": "current_unix_timestamp", "operator": "lte", "value": "1748736000"}
  ],
  "action": "ALLOW"
}

Solana: SOL Transfer Allowlist

{
  "name": "Allow SOL to treasury",
  "method": "signAndSendTransaction",
  "conditions": [
    {"field_source": "solana_system_program_instruction", "field": "instructionName", "operator": "eq", "value": "Transfer"},
    {"field_source": "solana_system_program_instruction", "field": "Transfer.to", "operator": "eq", "value": "TreasuryPubkey..."}
  ],
  "action": "ALLOW"
}

Solana: SOL Transfer Cap

{
  "name": "Max 1 SOL per tx",
  "method": "signAndSendTransaction",
  "conditions": [
    {"field_source": "solana_system_program_instruction", "field": "instructionName", "operator": "eq", "value": "Transfer"},
    {"field_source": "solana_system_program_instruction", "field": "Transfer.lamports", "operator": "lte", "value": "1000000000"}
  ],
  "action": "ALLOW"
}

Solana: SPL Token (USDC) Allowlist

{
  "name": "Allow USDC transfers to recipient",
  "method": "signAndSendTransaction",
  "conditions": [
    {"field_source": "solana_token_program_instruction", "field": "instructionName", "operator": "eq", "value": "TransferChecked"},
    {"field_source": "solana_token_program_instruction", "field": "TransferChecked.mint", "operator": "eq", "value": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},
    {"field_source": "solana_token_program_instruction", "field": "TransferChecked.destination", "operator": "eq", "value": "RecipientATA..."}
  ],
  "action": "ALLOW"
}

Solana: Program Allowlist

Only allow interactions with specific programs:

{
  "name": "Allow System and Token programs only",
  "method": "signAndSendTransaction",
  "conditions": [
    {"field_source": "solana_program_instruction", "field": "programId", "operator": "in", "value": [
      "11111111111111111111111111111111",
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
    ]}
  ],
  "action": "ALLOW"
}

Custom Restrictive Patterns

Use these only when the user explicitly requests tighter restrictions. Adapt the contract address and chain_id to the user's needs.

Contract-Specific Pattern

[
  {"name": "Allow <DAPP_NAME>", "method": "eth_sendTransaction", "conditions": [
    {"field_source": "ethereum_transaction", "field": "to", "operator": "eq", "value": "<CONTRACT_ADDRESS>"},
    {"field_source": "ethereum_transaction", "field": "chain_id", "operator": "eq", "value": "<CHAIN_ID>"}
  ], "action": "ALLOW"},
  {"name": "Token approvals on <NETWORK>", "method": "eth_sendTransaction", "conditions": [
    {"field_source": "ethereum_transaction", "field": "chain_id", "operator": "eq", "value": "<CHAIN_ID>"},
    {"field_source": "ethereum_transaction", "field": "value", "operator": "eq", "value": "0"}
  ], "action": "ALLOW"},
  {"name": "Deny key export", "method": "exportPrivateKey", "conditions": [], "action": "DENY"}
]

Chain-Restricted Pattern

[
  {"name": "Allow tx on <NETWORK>", "method": "eth_sendTransaction", "conditions": [
    {"field_source": "ethereum_transaction", "field": "chain_id", "operator": "eq", "value": "<CHAIN_ID>"}
  ], "action": "ALLOW"},
  {"name": "Allow signing on <NETWORK>", "method": "eth_signTypedData_v4", "conditions": [
    {"field_source": "ethereum_typed_data_domain", "field": "chainId", "operator": "eq", "value": "<CHAIN_ID>"}
  ], "action": "ALLOW"},
  {"name": "Deny key export", "method": "exportPrivateKey", "conditions": [], "action": "DENY"}
]

Wei / Lamports Quick Reference

EVM (wei)

Amount	Wei String
0.001 ETH	`"1000000000000000"`
0.01 ETH	`"10000000000000000"`
0.1 ETH	`"100000000000000000"`
1 ETH	`"1000000000000000000"`
10 ETH	`"10000000000000000000"`

Formula: wei = eth * 10^18

Solana (lamports)

Amount	Lamports String
0.001 SOL	`"1000000"`
0.01 SOL	`"10000000"`
0.1 SOL	`"100000000"`
1 SOL	`"1000000000"`
10 SOL	`"10000000000"`

Formula: lamports = sol * 10^9

USDC (6 decimals — same on EVM and Solana)

Amount	Raw String
1 USDC	`"1000000"`
100 USDC	`"100000000"`
1000 USDC	`"1000000000"`

Chain IDs (EVM)

Chain	ID (string in conditions)
Ethereum Mainnet	`"1"`
Ethereum Sepolia	`"11155111"`
Base	`"8453"`
Optimism	`"10"`
Arbitrum One	`"42161"`
Polygon	`"137"`
BSC	`"56"`

Common Solana Program IDs

Program	ID
System Program	`11111111111111111111111111111111`
Token Program	`TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA`
Token-2022	`TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb`
Associated Token	`ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL`
USDC Mint	`EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`

Interaction Guidelines

Ask about chain first — Determine if the user needs EVM, Solana, or both policies.
Clarify addresses — If the user says "allow transfers to my friend", ask for the address.
Confirm amounts — Convert user-friendly amounts (e.g. "1 ETH") to wei/lamports in the output.
Explain trade-offs — If a policy is overly permissive, warn the user. If too restrictive, note what will be blocked.
Combine smartly — Use multiple conditions per rule for AND, multiple rules for OR.
Always include deny-export — Recommend a DENY exportPrivateKey rule unless the user explicitly needs key export.
Output valid JSON — Every json:policy block must be valid, parseable JSON. Double-check addresses and values.
Rule name ≤ 50 characters — Privy API enforces a 50-character limit on rule names. NEVER include full on-chain addresses in rule names. Use short descriptive names like "Allowlist recipients", "Max 0.1 ETH per tx", or "Allow SOL to treasury". If you need to reference an address, abbreviate it (e.g. 0xba86...BE6E).

Do NOT

Do NOT output policy rules as code blocks or plain text — always call wallet_propose_policy
Do NOT add extra fields to rules (only: name, method, conditions, action)
Do NOT add extra fields to conditions (only: field_source, field, operator, value, plus abi/typed_data when needed)
Do NOT use Solana field_sources (solana_*) with chain_type="ethereum" or vice versa
Do NOT use lowercase action values — always "ALLOW" or "DENY"
Do NOT use ethereum_transaction or ethereum_calldata field_sources with eth_signTypedData_v4 — use ethereum_typed_data_domain or ethereum_typed_data_message instead
Do NOT use ethereum_transaction field_sources with eth_sign7702Authorization — use ethereum_7702_authorization instead
Do NOT use custom restrictive rules for a service unless the user explicitly asks for tighter restrictions — default to the wildcard policy

FAQ

What does the wallet-policy skill do?

How do I install wallet-policy?

Run npx skills add https://github.com/starchild-ai-agent/official-skills --skill wallet-policy in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/wallet-policy/ (personal) or .claude/skills/wallet-policy/ (project).

Which AI agents can use wallet-policy?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is wallet-policy safe to install?

Security partners have reviewed it: Gen Agent Trust Hub passed; Socket passed; Snyk flagged items to review; Runlayer passed. As with any skill, read the SKILL.md and bundled scripts before installing.

Who maintains wallet-policy?

It is published by starchild-ai-agent in starchild-ai-agent/official-skills. It has 4,061 recorded installs.