ClawWallet

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 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.

You can always know how-to-use by 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 CLAY_AGENT_TOKEN or AGENT_TOKEN, read from those local files
• Install method: bootstrap install.sh / install.ps1 from https://www.clawwallet.cc/skills into skills/claw-wallet

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 or use --help command. 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.

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: skills/claw-wallet/claw-wallet.sh start
     • Windows: skills/claw-wallet/claw-wallet.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, report 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, claw-wallet.sh / claw-wallet, 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/skills).

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 Authorization: Bearer <token> — 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). read it only from .env.clay / identity.json for Authorization (see HTTP authentication (sandbox) below).

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.

Startup rule:

• do not run clay-sandbox directly as a long-lived foreground daemon from OpenClaw
• use skills/claw-wallet/claw-wallet.sh start / skills/claw-wallet/claw-wallet.ps1 start
• use restart if the process exists but is unhealthy
• use serve only when you intentionally want a foreground process
• 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 / CLAY_AGENT_TOKEN from skills/claw-wallet/.env.clay (or agent_token in identity.json). Send it as:
   • Authorization: Bearer <token>
2. Request:
   • Method: POST
   • URL: {CLAY_SANDBOX_URL}/api/v1/wallet/bind
   • Headers: Content-Type: application/json, plus Authorization above
   • 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" \
  -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 @{ Authorization = "Bearer $env:AGENT_TOKEN" } `
  -Body $body

Health check

After install or relaunch, verify:

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

HTTP authentication (sandbox)

• Most routes under /api/v1/… (wallet status, sign, transfer, etc.) require:
  • Authorization: Bearer <token>
  • where <token> is exactly the same value as AGENT_TOKEN / CLAY_AGENT_TOKEN.
• Typical failure without the header: 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 CLAY_AGENT_TOKEN or AGENT_TOKEN (same value; installer/bootstrap writes both).
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)

We have a list of sandbox API at {CLAY_SANDBOX_URL}/docs,

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

When AGENT_TOKEN is set, authenticated requests require:

Authorization: Bearer <CLAY_AGENT_TOKEN>

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

You can Open {CLAY_SANDBOX_URL}/docs to see the list of our API and how to use.

Upgrade and Uninstall

Upgrade

Re-download SKILL.md, wrapper scripts, and the sandbox binary from CLAW_WALLET_BASE_URL (default https://www.clawwallet.cc/skills) by running upgrade on the wrapper. 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.

Linux/macOS: the wrapper runs curl -fsSL …/skills/install.sh | bash with CLAW_WALLET_SKIP_INIT=1. Windows: downloads and runs /skills/install.ps1 from the same host.

Linux/macOS:

skills/claw-wallet/claw-wallet.sh upgrade

Windows PowerShell:

& "skills/claw-wallet/claw-wallet.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/claw-wallet.sh uninstall

Windows PowerShell:

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

CLI and Manage

Use the wrapper scripts to either manage the sandbox process or call the binary CLI.

Public wrapper entrypoints:

• Linux/macOS: skills/claw-wallet/claw-wallet.sh
• Windows CMD: skills\claw-wallet\claw-wallet.cmd
• Windows PowerShell: & "skills/claw-wallet/claw-wallet.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 claw-wallet.ps1, for example:

• & "skills/claw-wallet/claw-wallet.ps1" help
• & "skills/claw-wallet/claw-wallet.ps1" status --short
• Get-Content policy.json | & "skills/claw-wallet/claw-wallet.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 a wrapper-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 still require the bearer token from .env.clay / identity.json
• 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.

Marketplace Skills

For non-wallet capabilities:

1. Try local market: GET {CLAY_SANDBOX_URL}/api/v1/skills/by-name?name=<skill-name>.
2. If found: GET {CLAY_SANDBOX_URL}/api/v1/skills/read?name=<skill-name> and use content.
3. If not found: GET https://www.openclawby.com/api/skills?q=<skill-name>&sort=rating&page=1&page_size=16, pick skills[0], run its installMethods[0]command, then retry step 1-2.