wallet

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

Security Scan

The skill's declared purpose (local sandbox wallet) matches most of its files and required secrets, but the installer fetches and executes binaries/scripts from an external site (www.clawwallet.cc) rather than a well-known release host and there is a small metadata inconsistency about autonomous invocation — both raise non-trivial supply-chain risk.

Purpose & Capability

Name, description, declared config paths (.env.clay, identity.json), and required env vars (CLAY_SANDBOX_URL, CLAY_AGENT_TOKEN/AGENT_TOKEN) align with a local wallet sandbox. Required shells/curl are reasonable for the installer and wrapper scripts.

Instruction Scope

SKILL.md and the included scripts instruct the agent to read local secret files and call the sandbox HTTP API (expected), but also instruct running a remote bootstrap installer (curl | bash) and automatically initializing the wallet via the sandbox API using tokens found in local files. The install/init flow therefore includes actions that execute remote code and make authenticated API calls on behalf of the agent — these are powerful steps and increase risk if the remote content is untrusted.

Install Mechanism

The installer is a bootstrap script that downloads wrapper scripts and a platform binary from https://www.clawwallet.cc (curl -fsSL | bash and curl -L to fetch binaries). The distribution host is not a standard vetted release host (e.g., GitHub releases) and the installer writes and executes a downloaded binary in the skill workspace. This is a high-risk install pattern (supply-chain / remote-execution risk) unless you can verify provenance, checksums, or signatures.

Credentials

Requested environment variables (CLAY_SANDBOX_URL, CLAY_AGENT_TOKEN, AGENT_TOKEN) and local config files are directly relevant to a local sandbox wallet and expected. The primary credential is an API bearer token used to control the local sandbox; while sensitive, it is required for wallet operations. No unrelated credentials or system-wide secrets are requested.

Persistence & Privilege

The skill requests writing only to its workspace (skills/claw-wallet/**) and starting a long-lived sandbox process (expected for a local wallet). always is false. However there is a small inconsistency: registry-level flags indicate model invocation is allowed by default, while the skill metadata declares autonomousInvocation: false and model-invocation should 'require-user-confirmation'. Clarify whether the agent/platform will permit autonomous invocations despite the skill's intent to require confirmations.

What to consider before installing

This skill appears coherent for a local wallet, but exercise caution before installing because the installer and sandbox binary are fetched and executed from https://www.clawwallet.cc (not a standard release host). Before proceeding: (1) review the remote install.sh/install.ps1 and the sandbox binary's provenance (source repo, signed checksums, or PGP/GitHub release signatures); (2) prefer installing from a vetted source (GitHub releases) or run the installer in an isolated environment; (3) verify .env.clay and identity.json are only created/read within the skill workspace and do not contain unrelated secrets; (4) confirm how the platform enforces 'require-user-confirmation' and that the agent will not autonomously execute transactions or reinstall/upgrade without explicit confirmation; (5) backup any wallet state before uninstall/upgrade and consider running the sandbox inside a restricted container/VM. If the distributor can provide signed release artifacts, reproducible build provenance, or host the installer/binaries on a trusted release provider, the assessment could be upgraded to benign.

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.