claw-wallet-basic

name	claw-wallet-basic
description	A multi-chain wallet skill for AI agents, with local sandbox signing, secure PIN handling, and configurable risk controls.

Use this skill when...

Use this skill when the user wants to bind, unlock, or recover a wallet for an AI agent.

Use this skill when the user wants to sign messages, sign transactions, or transfer assets through a policy-controlled wallet flow.

Use this skill when the user wants to interact with supported DeFi flows such as swap.

Use this skill when the user asks about x402 payment, gas sponsorship, or paying gas with USDC during managed transfer/swap/invoke flows.

Use this skill when the user wants to inspect wallet balances, token holdings, addresses, wallet status, or transaction history.

Use this skill when the user wants to manage wallet security policies such as chain allowlists, token allowlists, transfer limits, or confirmation thresholds.

Use this skill when the user wants to turn a completed DeFi sequence into a reusable SDK-backed script or a common workflow template.

Always learn the current sandbox API from Swagger UI at {CLAY_SANDBOX_URL}/docs.

claw wallet skill

This skill equips an OpenClaw agent with a local multi-chain wallet sandbox.

Registry metadata

• Required local config files: skills/claw-wallet/.env.clay and skills/claw-wallet/identity.json
• Required sandbox connection values: CLAY_SANDBOX_URL plus optional AGENT_TOKEN, read from those local files
• Install method: bootstrap install.sh / install.ps1 from https://www.clawwallet.cc/skills into skills/claw-wallet
• Companion skills to load together when present: claw-wallet-basic, wallet-chain-explorer, claw-wallet-defi-scripts

Privilege safety rule

• First-time install and normal start / restart do not require extra confirmation.
• Reinstall, upgrade, uninstall, and transaction execution do require explicit user confirmation.
• Limit writes to the skill workspace under skills/claw-wallet/**.

1. All wallet-related operations must go through the local sandbox. Use the localhost API or sandbox CLI instead. Open {CLAY_SANDBOX_URL}/docs. If sandbox is not running, start/restart it first.
2. Before executing any transaction, the agent must ask the user for confirmation (e.g. "Confirm to execute this transaction?"). Do not proceed without explicit user consent.
3. Before using a concrete sandbox feature, open {CLAY_SANDBOX_URL}/docs, read the relevant endpoint, request schema, field names, field meanings, and response notes, then call the API exactly as documented. Do not invent field names or overthink parameters beyond what the docs require.

Bootstrap

Installation path

All files live in one directory:

{your_workspace}/skills/claw-wallet/

Platform	Resolved path
Linux/macOS	skills/claw-wallet/ (relative to workspace root)
Windows	skills\claw-wallet\ (relative to workspace root)

Install

Before downloading or running the installer, first check from the workspace root whether skills/claw-wallet already exists (same path as in Installation path below). Use that check to decide whether this is a reuse flow or a new install flow.

• If it exists: Do not run the remote installer or install.sh / install.ps1 bootstrap unless the user explicitly wants a reinstall.

  1. Start the sandbox first.
     • Linux/macOS: bash skills/claw-wallet/install.sh start
     • Windows: & "skills/claw-wallet/install.ps1" start
     • Use restart if the sandbox is unhealthy.
  2. Call POST {CLAY_SANDBOX_URL}/api/v1/wallet/init with Authorization: Bearer <token> from .env.clay.
     • This call is idempotent, so it is safe to run even when the wallet already exists.
  3. Call GET {CLAY_SANDBOX_URL}/api/v1/wallet/status with the same bearer token and get status, report to the user with the *status.
  4. If relay_user_bound is false or relay_binding_status is not valid, Do not explain the flow, just output the bind_url, bind_url https://www.clawwallet.cc/claim/<uid> to the user, hint them to bind their agent wallet+.
  5. Stop here after the report. Do not bootstrap again unless the user explicitly asks for reinstall.

• If it does not exist: Continue with Bootstrap (curl install) below.

Bootstrap (curl install)

Skill files are hosted at https://www.clawwallet.cc. Create the skill directory, cd into it, then pipe the remote installer into bash (Linux/macOS) or run the PowerShell installer (Windows). The installer downloads SKILL.md, install.sh / install.ps1, compatibility wrappers, and the sandbox binary, then initializes the wallet.

Do not run reinstall or upgrade automatically. First-time install is allowed without extra confirmation.

Linux/macOS:

mkdir -p skills/claw-wallet
cd skills/claw-wallet
curl -fsSL https://www.clawwallet.cc/skills/install.sh | bash

Windows PowerShell (from workspace root; run after creating skills\claw-wallet):

New-Item -ItemType Directory -Path "skills\claw-wallet" -Force | Out-Null
Set-Location "skills\claw-wallet"
Invoke-WebRequest -Uri "https://www.clawwallet.cc/skills/install.ps1" -OutFile "install.ps1" -UseBasicParsing
& ".\install.ps1"

Optional: override the download host with environment variable CLAW_WALLET_BASE_URL (defaults to https://www.clawwallet.cc).

After the installer finishes, immediately run the status disclosure flow and emit the fixed disclosure format below.

After install, use GET {CLAY_SANDBOX_URL}/api/v1/wallet/status with the Authorization rule from HTTP authentication (sandbox) below and confirm wallet is ready. The response includes address information and uid (when present). You must show the user: wallet addresses (from the response), uid (from the response when present) (HTTP API under /api/v1/..., Swagger at /docs, same origin).

Use this exact format to respond to the user after finishing the install:

• Wallet ready

• Addresses: <address map from wallet/status>

• UID: <uid from wallet/status/identity.json>

• AGENT_TOKEN: <agent_token from .env.clay or identity>

• Tell the user: To fully control your wallet with a better experience, open https://www.clawwallet.cc/claim/<uid> (substitute <uid> with the value from wallet/status) to register and bind your sandbox wallet within 15 minutes. then reply complete bind when you're done - I'll verify the binding status and walk you through everything the wallet can do.

• After the user says they completed the bind workflow, tell them: You can use this wallet to transfer, receive, and perform complex DeFi interactions.

Wallet lock routing rules

• Always inspect GET {CLAY_SANDBOX_URL}/api/v1/wallet/status before telling the user how to recover a locked wallet.
• Treat the wallet as bound / provisioned when either of these is true:
  • relay_user_bound is true and relay_binding_status is valid
  • has_provisioned_share1 is true
  • status is provisioned_waiting_for_pin
• For a bound / provisioned wallet:
  • Do not ask the user to send their PIN to the agent.
  • Do not ask the user to paste a PIN into chat.
  • Tell the user to open https://www.clawwallet.cc/dashboard and unlock the wallet there.
• For an unbound / local wallet:
  • If can_reactivate_locally is true, call POST {CLAY_SANDBOX_URL}/api/v1/wallet/reactivate.
  • Do not ask the user for a PIN in this branch.
  • If reactivation succeeds, continue with the wallet task.
• If the wallet is unbound and can_reactivate_locally is false, explain that local reactivation is unavailable in the current sandbox state instead of inventing a PIN flow.

Startup rule:

• do not run clay-sandbox directly as a long-lived foreground daemon from OpenClaw
• use bash skills/claw-wallet/install.sh start / & "skills/claw-wallet/install.ps1" start
• use restart if the process exists but is unhealthy
• use serve only when you intentionally want a foreground process
• Do not assume start / restart has already unlocked the wallet.
• After start / restart, inspect GET {CLAY_SANDBOX_URL}/api/v1/wallet/status and follow the wallet lock routing rules above.
• For an unbound / local wallet, the agent should still explicitly try POST {CLAY_SANDBOX_URL}/api/v1/wallet/reactivate when can_reactivate_locally is true.
• If the user wants balances or transaction history, call POST {CLAY_SANDBOX_URL}/api/v1/wallet/refresh first, or use refreshAndAssets for a fresh balance snapshot.

Register and bind (website vs agent)

End users (browser): Open https://www.clawwallet.cc/claim/<uid> in the browser, substituting <uid> with the wallet uid from wallet/status, to start the bind flow; the /claim/... path must include that uid (see Claw Wallet).

Agents (automating bind after the user starts the flow): The user will obtain a message_hash_hex from the Claw bind / challenge step and paste or send it to you. You must call the sandbox bind API with the same bearer token used for all authenticated sandbox requests.

1. Token: Use AGENT_TOKEN from skills/claw-wallet/.env.clay (or agent_token in identity.json). If it has a value, send it as:
   • Authorization: Bearer <AGENT_TOKEN>
2. Request:
   • Method: POST
   • URL: {CLAY_SANDBOX_URL}/api/v1/wallet/bind
   • Headers: Content-Type: application/json, plus Authorization only when AGENT_TOKEN has a value
   • Body (JSON): { "message_hash_hex": "<value from user>" }
3. Behavior: The sandbox signs locally and forwards the result to the relay

Example (bash / Linux / macOS): curl is usually available.

curl -sS -X POST "${CLAY_SANDBOX_URL}/api/v1/wallet/bind" \
  -H "Content-Type: application/json" \
  ${AGENT_TOKEN:+-H "Authorization: Bearer ${AGENT_TOKEN}"} \
  -d "{\"message_hash_hex\":\"<hex from user>\"}"

Windows: A plain CMD window may not have curl on older systems, or agents may run only PowerShell. Prefer one of:

• PowerShell 7+ / Windows Terminal often ships with curl.exe (real curl). If curl --version works, the bash example above is fine (use $env:CLAY_SANDBOX_URL / $env:AGENT_TOKEN or substitute literals).
• If curl is missing or fails, use Invoke-RestMethod (built in):

$body = @{ message_hash_hex = "<hex from user>" } | ConvertTo-Json
Invoke-RestMethod -Method Post -Uri "$env:CLAY_SANDBOX_URL/api/v1/wallet/bind" `
  -ContentType "application/json" `
  -Headers $(if ($env:AGENT_TOKEN) { @{ Authorization = "Bearer $env:AGENT_TOKEN" } } else { @{} }) `
  -Body $body

Health check

After install or relaunch, verify:

• GET {CLAY_SANDBOX_URL}/health
• expected response: {"status":"ok"}

HTTP authentication (sandbox)

• When AGENT_TOKEN has a value, send it on protected /api/v1/... requests:
  • Authorization: Bearer <AGENT_TOKEN>
• When AGENT_TOKEN is empty, omit the Authorization header. This is allowed sandbox behavior.
• Typical failure with a wrong token: HTTP 401 with body Unauthorized: invalid claw wallet sandbox token.

Where to read the token (same secret, duplicated for convenience)

Location	Field(s)
skills/claw-wallet/.env.clay	CLAY_SANDBOX_URL — base URL (scheme, host, port) for the sandbox HTTP server (API /api/v1/..., /docs). Also AGENT_TOKEN when the user has set one.
skills/claw-wallet/identity.json	agent_token

Example workspace test layout (same idea):

• wallet_test/<sim>/.env.clay
• wallet_test/<sim>/identity.json

Swagger UI (/docs)

All available sandbox features are shown in Swagger UI at {CLAY_SANDBOX_URL}/docs. Read this page before using a specific feature.

When a request needs fields, use the exact field names and meanings from the endpoint schema. For example, if the schema says amount_wei, send amount_wei; do not rename it to amount, value, or another inferred name unless the docs for that endpoint say so.

Unauthenticated or special paths (examples)

• GET /health — no bearer required
• GET /docs, GET /openapi.yaml — no bearer (documentation only)
• Exact list is defined by the sandbox binary; see /openapi.yaml on a running sandbox

Primary wallet API

Use the token value from .env.clay or identity.json as described in HTTP authentication (sandbox) above.

Open {CLAY_SANDBOX_URL}/docs to see every available API and how to use it.

Upgrade and Uninstall

Upgrade

Re-download SKILL.md, the local install entrypoint, compatibility wrappers, and the sandbox binary from CLAW_WALLET_BASE_URL (default https://www.clawwallet.cc/skills) by running upgrade on install.sh / install.ps1. Wallet data (.env.clay, identity.json, share3.json) is preserved.

Ask the user for confirmation before upgrade, because it rewrites files in skills/claw-wallet/** and may restart the sandbox environment.

The same local entrypoint is used for first install and day-2 operations:

• No argument: first install flow, including wallet initialization
• upgrade: re-download files and binary, but skip wallet initialization
• start / restart / stop / is-running / serve / uninstall: runtime management commands

Linux/macOS:

bash skills/claw-wallet/install.sh upgrade

Windows PowerShell:

& "skills/claw-wallet/install.ps1" upgrade

Uninstall

If you are an agent:

1. You must ask the user for permission before executing the uninstall command. Do not run it automatically.
2. You must inform the user: "Before uninstalling, you must backup .env.clay, identity.json, and share3.json if you need to recover the wallet later. Deletion is irreversible."
3. Proceed only after the user has explicitly confirmed.

If you are a user: Before uninstalling, you must backup .env.clay, identity.json, and share3.json if you need to recover the wallet later. Deletion is irreversible.

The uninstall script will:

1. Stop the sandbox process
2. Display a warning and ask for confirmation
3. Proceed only if you type yes
4. Remove the entire skill directory

Linux/macOS:

bash skills/claw-wallet/install.sh uninstall

Windows PowerShell:

& "skills/claw-wallet/install.ps1" uninstall

CLI and Manage

Use the local install entrypoint to either manage the sandbox process or call the binary CLI. Compatibility wrappers still exist, but prefer install.sh / install.ps1.

Primary entrypoints:

• Linux/macOS: bash skills/claw-wallet/install.sh
• Windows CMD: powershell -NoProfile -ExecutionPolicy Bypass -File "skills\claw-wallet\install.ps1"
• Windows PowerShell: & "skills/claw-wallet/install.ps1"

Process management:

• start starts the sandbox in the background when it is installed but not running
• stop stops the sandbox
• restart stops and then starts again
• is-running exits 0 when the sandbox is running, 1 otherwise
• upgrade re-downloads skill files and the sandbox binary from the configured host and reruns the installer (no git)
• uninstall stops the sandbox, asks for confirmation, and removes the skill directory

CLI commands:

• help, -h, --help print the built-in CLI usage text
• status --short prints a one-line status summary
• addresses prints the wallet address map
• history [chain] [limit] prints transaction history through GET /api/v1/wallet/history; chain and limit are optional query filters applied in memory. Example: history solana 20
• assets prints cached multichain balances through GET /api/v1/wallet/assets
• refreshAndAssets prints a fresh balance snapshot by combining refresh + assets in one request
• prices prints the oracle price cache
• security prints the security and risk cache
• audit [number] prints recent audit log entries
• refresh triggers an async asset refresh through POST /api/v1/wallet/refresh
• broadcast signed-tx.json broadcasts a signed transaction payload
• transfer transfer.json builds, signs, and submits a transfer payload
• policy get prints the local policy.json via GET /api/v1/policy/local (read-only). The merged policy view also appears on GET /api/v1/wallet/status under policy.
• Policy cannot be changed from the sandbox CLI or a generic sandbox POST API. After the wallet is bound, users adjust limits and rules in the frontend; the relay may also push policy updates to the sandbox (file on disk).

Windows equivalents use the same subcommands through install.ps1, for example:

• & "skills/claw-wallet/install.ps1" help
• & "skills/claw-wallet/install.ps1" status --short
• Get-Content policy.json | & "skills/claw-wallet/install.ps1" policy set -

Help and usage:

• help, -h, and --help are equivalent for the sandbox binary
• These flags print the built-in CLI usage text from the binary itself, not an install-script-specific summary
• The help output is grouped by area: server, wallet read commands, policy, transaction helpers, and local bootstrap / utility commands
• Wallet read commands are thin wrappers over the local HTTP API and use AGENT_TOKEN from .env.clay / identity.json when it has a value
• Running the binary with no subcommand starts the HTTP server, so use help explicitly when you want usage text instead of a foreground daemon

Refresh policy

Use refresh only when it protects correctness:

• Must refresh before transfer, swap, invoke, or any action that depends on fresh balances, history, price, or risk.
• The sandbox already refreshes automatically in the corresponding managed execution paths when it needs to.
• For manual refresh, use the sandbox refresh CLI command or the POST /api/v1/wallet/refresh API.
• If you need a fresh snapshot immediately after refresh, prefer refreshAndAssets instead of assets alone.
• For OpenClaw / agent automation, call the sandbox refresh API explicitly before transaction execution when the cached state may be stale.
• Do not refresh on every read. Assets/history views should stay cache-first unless the cache is stale or the user explicitly requests a refresh.