@agentlayer.tech/wallet 0.1.0

package/README.md

@@ -0,0 +1,332 @@
+![AgentLayer](logo+name.png)
+
+# AgentLayer
+
+AgentLayer is a beta local-first wallet and finance stack for agents.
+
+The repository includes:
+
+- `agent-wallet/` - the main wallet backend for AgentLayer
+- `.openclaw/` - the local AgentLayer bridge layer
+- `wdk-btc-wallet/` - the local Bitcoin wallet service
+- `wdk-evm-wallet/` - the local EVM wallet service
+- `provider-gateway/` - shared provider access for Solana RPC, Bags, and related finance reads
+- `mcp-server/` - the finance and crypto MCP layer
+
+The goal is simple:
+
+- keep wallet secrets local
+- let agents use constrained wallet capabilities
+- support real onchain flows without giving agents direct key ownership
+
+## Beta
+
+This project is in beta.
+
+Do not treat it as a finished production wallet stack. Test every flow before relying on it.
+
+## Quick install
+
+System prerequisites:
+
+- `python3`
+- `node`
+- `npm`
+
+Install from the latest GitHub release bundle:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/lopushok9/Agent-Layer/main/install-from-github.sh | sh
+```
+
+Install through npm:
+
+```bash
+npx @agentlayer.tech/wallet install --yes
+```
+
+Or install the CLI globally first:
+
+```bash
+npm install -g @agentlayer.tech/wallet
+openclaw-agent-wallet install --yes
+```
+
+The npm CLI runs the same bundled installer, but uses a versioned runtime layout:
+
+```bash
+~/.openclaw/agent-wallet-runtime/releases/<version>
+~/.openclaw/agent-wallet-runtime/current
+```
+
+`--yes` generates local runtime secrets when this is the first install. The installer stores `master_key` and `approval_secret` in `~/.openclaw/sealed_keys.json`; only the boot key needed to unlock that sealed bundle is written to the installed runtime `.env`.
+
+Useful npm CLI commands:
+
+```bash
+openclaw-agent-wallet status
+openclaw-agent-wallet doctor
+openclaw-agent-wallet update --yes
+openclaw-agent-wallet rollback
+```
+
+Install from a local clone:
+
+```bash
+sh ./setup.sh
+```
+
+If you want the installer to finish the OpenClaw plugin wiring in the same pass, provide the runtime secrets before running it:
+
+Solana:
+
+```bash
+export AGENT_WALLET_BOOT_KEY="$(openssl rand -base64 32)"
+export AGENT_WALLET_MASTER_KEY="$(openssl rand -base64 32)"
+export AGENT_WALLET_APPROVAL_SECRET="$(openssl rand -base64 32)"
+```
+Bitcoin:
+
+```bash
+sh agent-wallet/scripts/setup_btc_wallet.sh
+```
+
+EVM:
+
+```bash
+cd wdk-evm-wallet && sh run-local.sh
+```
+
+Create a local EVM wallet binding for an OpenClaw user:
+
+```bash
+printf '%s\n' 'your-local-evm-password' | \
+agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-create \
+  --user-id your-user-id \
+  --password-stdin \
+  --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
+```
+
+Unlock an existing EVM wallet binding:
+
+```bash
+printf '%s\n' 'your-local-evm-password' | \
+agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-unlock \
+  --user-id your-user-id \
+  --password-stdin \
+  --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
+```
+
+That generates three fresh local secrets in the current shell session. If you prefer Python instead of `openssl`:
+
+```bash
+python3 -c "import secrets; print(secrets.token_urlsafe(32))"
+```
+
+Run it three times and assign the outputs to:
+
+- `AGENT_WALLET_BOOT_KEY`
+- `AGENT_WALLET_MASTER_KEY`
+- `AGENT_WALLET_APPROVAL_SECRET`
+
+Without those secrets, the installer still lays down the runtime and installs dependencies, but it stops short of the final hardened OpenClaw config step and prints the exact `next_configure_command` you should run after secrets are available.
+
+## Connect the MCP server
+
+```json
+{
+  "mcpServers": {
+    "agent-layer": {
+      "url": "https://agent-layer-production-852f.up.railway.app/mcp"
+    }
+  }
+}
+```
+
+## What you get after install
+
+If you install from GitHub release, the bundle is extracted under:
+
+```bash
+~/.openclaw/agent-wallet-runtime/current
+```
+
+The installer then does the following:
+
+- creates `agent-wallet/.env` from `agent-wallet/.env.example` if it does not exist
+- creates `agent-wallet/.venv` and installs the Python backend with `pip install -e`
+- installs Node dependencies for `wdk-btc-wallet` and `wdk-evm-wallet`
+- creates a minimal `~/.openclaw/openclaw.json` if one does not exist
+- if the required secrets are already present, writes or updates `~/.openclaw/sealed_keys.json`
+- if the required secrets are already present, patches `~/.openclaw/openclaw.json` to load the `agent-wallet` extension and point it at the installed runtime
+
+When the installer reaches the final config step, the default plugin config is:
+
+- `backend=solana_local`
+- `network=devnet`
+
+## What is not done automatically
+
+The installer does not:
+
+- create a BTC wallet
+- unlock a BTC wallet
+- create an EVM wallet
+- unlock an EVM wallet
+- start the local `wdk-btc-wallet` service
+- start the local `wdk-evm-wallet` service
+- expose seed phrases to the agent
+- install `python3`, `node`, or `npm` for you
+
+For Solana specifically, install alone does not make signed transactions available. You still need a readable wallet identity:
+
+- read-only mode: `SOLANA_AGENT_PUBLIC_KEY`
+- signing mode: a sealed `private_key` or `SOLANA_AGENT_KEYPAIR_PATH`
+
+## BTC setup
+
+The BTC path already has a one-command host bootstrap wrapper:
+
+```bash
+sh agent-wallet/scripts/setup_btc_wallet.sh
+```
+
+That flow:
+
+- prompts for `user-id`
+- prompts for `mainnet`, `testnet`, or `regtest`
+- defaults to `http://127.0.0.1:8080`
+- can auto-start `wdk-btc-wallet/run-local.sh` if the local service is not already healthy
+- creates or unlocks the local BTC wallet binding
+- patches OpenClaw config to `backend=wdk_btc_local`
+
+BTC setup only supports localhost service URLs. The local BTC service is protected by a bearer token stored at:
+
+```bash
+~/.openclaw/wdk-btc-wallet/local-auth-token
+```
+
+If you need to reveal the BTC seed phrase later, that remains a host-side step:
+
+```bash
+sh agent-wallet/scripts/reveal_btc_seed.sh
+```
+
+## EVM setup
+
+The EVM runtime is installed by `setup.sh`, but the host-side wallet onboarding is still a manual CLI flow.
+
+Start the local EVM service:
+
+```bash
+cd wdk-evm-wallet && sh run-local.sh
+```
+
+Create a local EVM wallet binding for an OpenClaw user:
+
+```bash
+printf '%s\n' 'your-local-evm-password' | \
+agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-create \
+  --user-id your-user-id \
+  --password-stdin \
+  --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
+```
+
+Unlock an existing EVM wallet binding:
+
+```bash
+printf '%s\n' 'your-local-evm-password' | \
+agent-wallet/.venv/bin/python -m agent_wallet.openclaw_cli evm-wallet-unlock \
+  --user-id your-user-id \
+  --password-stdin \
+  --config-json '{"backend":"wdk_evm_local","network":"base","wdkEvmServiceUrl":"http://127.0.0.1:8081"}'
+```
+
+Then switch the OpenClaw plugin config to the EVM backend:
+
+```bash
+AGENT_WALLET_BOOT_KEY='...' \
+agent-wallet/.venv/bin/python agent-wallet/scripts/install_openclaw_local_config.py \
+  --backend wdk_evm_local \
+  --network base \
+  --user-id your-user-id \
+  --package-root agent-wallet \
+  --extension-path .openclaw/extensions/agent-wallet \
+  --python-bin agent-wallet/.venv/bin/python
+```
+
+That final config step assumes `~/.openclaw/sealed_keys.json` already exists. The normal path is to let the main installer create it by running install with `AGENT_WALLET_BOOT_KEY`, `AGENT_WALLET_MASTER_KEY`, and `AGENT_WALLET_APPROVAL_SECRET` available.
+
+Important EVM notes:
+
+- only localhost service URLs are supported for the OpenClaw EVM flow
+- the local EVM service uses a bearer token at `~/.openclaw/wdk-evm-wallet/local-auth-token`
+- the agent-facing EVM surface is intentionally narrow: balances, fee rates, receipts, transfers, Velora swaps, Aave V3 account/reserve/position flows, and Lido staking/withdrawal flows
+- Velora swap and Aave V3 support are currently limited to `ethereum` and `base`
+- Lido support is currently limited to `ethereum` and exposes read-only staking APR data from Lido's public API in the overview response
+
+## Solana notes
+
+The installer defaults the plugin to `solana_local` on `devnet`.
+
+The Solana runtime uses hardened local secrets:
+
+- `AGENT_WALLET_BOOT_KEY` is required by the runtime
+- `master_key` and `approval_secret` should live in `~/.openclaw/sealed_keys.json`
+- `AGENT_WALLET_MASTER_KEY` and `AGENT_WALLET_APPROVAL_SECRET` are provisioning inputs for installer/admin flows, not long-term runtime env
+
+Read-only Solana mode:
+
+```bash
+export SOLANA_AGENT_PUBLIC_KEY='...'
+```
+
+Signing Solana mode can use either:
+
+- a sealed `private_key` stored in `sealed_keys.json`
+- `SOLANA_AGENT_KEYPAIR_PATH`
+
+The default shared path already includes:
+
+- hosted provider-gateway defaults
+- shared Solana RPC path unless you override it
+
+You only need to bring your own RPC if you want to override the default route. Supported override paths are:
+
+- `SOLANA_RPC_URL`
+- `SOLANA_RPC_URLS`
+- `ALCHEMY_API_KEY`
+- `HELIUS_API_KEY`
+
+Automatic local Solana wallet creation exists, but it is off by default:
+
+```bash
+SOLANA_AUTO_CREATE_WALLET=false
+```
+
+## Security model
+
+The core rule is:
+
+the agent gets wallet capabilities, not wallet ownership.
+
+That means:
+
+- secret material stays local
+- signing stays in the wallet layer
+- risky writes require approval
+- BTC and EVM password-gated wallet operations remain host-side
+
+## License and community use
+
+This repository is public and source-available under the `PolyForm Small Business License 1.0.0`.
+
+If you are an individual developer, researcher, student, security reviewer, or hobbyist, you can:
+
+- read and audit the code
+- fork the repo
+- run it locally
+- modify it for yourself
+- open issues and send pull requests
+
+If you are using the project for a company, the license allows use for small businesses covered by the PolyForm thresholds. If you need rights beyond that, reach out for a separate commercial license.

package/RELEASING.md

@@ -0,0 +1,204 @@
+# Releasing
+
+## npm installer package
+
+The production installer is published as:
+
+```text
+@agentlayer.tech/wallet
+```
+
+Expected user install path:
+
+```bash
+npx @agentlayer.tech/wallet install --yes
+```
+
+The npm package ships source and installer scripts only. It must not ship local
+state such as `node_modules/`, `.venv/`, `__pycache__/`, wallet files, or
+OpenClaw secrets.
+
+Before publishing a tag, verify locally:
+
+```bash
+npm run check
+python3 agent-wallet/tests/smoke_npm_installer.py
+python3 agent-wallet/tests/smoke_install_agent_wallet.py
+npm --cache /tmp/npm-cache pack --dry-run
+```
+
+The GitHub workflow `.github/workflows/npm-installer.yml` verifies the package
+on pull requests and publishes tagged releases to npm. Repository secrets must
+include:
+
+```text
+NPM_TOKEN
+```
+
+Publish stable releases from version tags:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+The workflow runs:
+
+```bash
+npm publish --access public --provenance
+```
+
+For pre-release channels, publish manually or extend the workflow with npm
+dist-tags:
+
+```bash
+npm publish --access public --tag beta
+npm dist-tag add @agentlayer.tech/wallet@0.1.0-beta.1 beta
+```
+
+Runtime updates are versioned under:
+
+```text
+~/.openclaw/agent-wallet-runtime/releases/<version>
+~/.openclaw/agent-wallet-runtime/current
+```
+
+The CLI switches `current` only after a successful install/update. `rollback`
+switches `current` back to the recorded previous runtime or to a specific
+installed version.
+
+This repository's `v0.1.0-beta.2` public release should be framed around six repo-owned deliverables:
+
+1. `mcp-server/` - the finance and crypto MCP server
+2. `agent-wallet/` - the Python wallet backend
+3. `.openclaw/extensions/agent-wallet/` - the repo-shipped OpenClaw extension bridge
+4. `wdk-btc-wallet/` - the BTC-only wallet service built on Tether WDK
+5. `provider-gateway/` - the shared non-custodial provider access layer
+6. `docs/` - the Starlight-based documentation site
+
+### Release title
+
+```text
+AgentLayer Beta v0.1.0-beta.2
+```
+
+### Release body
+
+```md
+This is the second public beta release of the OpenClaw finance stack.
+
+This release keeps the original beta foundation and adds three new repo-owned components:
+
+- `mcp-server/` - finance and crypto MCP server
+- `agent-wallet/` - Python wallet backend
+- `.openclaw/extensions/agent-wallet/` - OpenClaw extension bridge for the wallet backend
+- `wdk-btc-wallet/` - BTC-only wallet service for local Bitcoin operations
+- `provider-gateway/` - shared provider access for hosted Solana RPC defaults, Bags, and Jupiter Earn
+- `docs/` - documentation app for setup, architecture, and capability reference
+
+## Highlights
+
+- Expands the beta stack with a dedicated local BTC wallet service
+- Adds a non-custodial shared provider gateway for Solana RPC, Bags, and Jupiter Earn
+- Adds a separate documentation app for onboarding and reference material
+- Keeps the MCP server, wallet backend, and OpenClaw extension bridge as the core beta foundation
+
+## Included in this release
+
+### New in `v0.1.0-beta.2`
+
+#### `wdk-btc-wallet/`
+
+- Separate BTC-only wallet service built on top of Tether WDK
+- Local encrypted wallet vault, localhost-only HTTP surface, and local bearer-token auth
+- Covers Bitcoin network selection, wallet lifecycle, balances, transfers, fees, and spendability
+
+#### `provider-gateway/`
+
+- Shared non-custodial provider layer for onboarding-friendly defaults
+- Hosted Solana RPC gateway with method allowlist
+- Shared Bags launch and fees access plus shared Jupiter Earn relay
+
+#### `docs/`
+
+- Separate Starlight-based documentation app for AgentLayer
+- Covers getting started, infrastructure boundaries, wallet architecture, and capabilities
+- Gives the beta stack a repo-owned documentation surface for onboarding and review
+
+### Existing beta foundation
+
+#### `mcp-server/`
+
+- MCP server for crypto, DeFi, gas, on-chain, and agent identity workflows
+- Structured tools for market data, protocol analytics, and blockchain lookups
+- Self-hostable base for OpenClaw or other MCP-compatible clients
+
+#### `agent-wallet/`
+
+- Local Solana wallet backend for OpenClaw-connected agents
+- Read, preview, prepare, and approval-gated execute flows
+- Local secret handling and explicit operator approval model for risky actions
+
+#### `.openclaw/extensions/agent-wallet/`
+
+- Thin TypeScript bridge from OpenClaw into the Python wallet backend
+- Repo-tracked plugin manifest and config schema
+- Keeps wallet policy and execution logic in Python while exposing a small operational tool surface to OpenClaw
+
+## Beta notes
+
+- This is a beta release and should not be treated as production-ready custody infrastructure
+- Mainnet use should remain cautious, explicit, and operator-controlled
+- Early feedback on usability, safety, and integration gaps is expected and welcome
+```
+
+## Suggested release note structure
+
+### Highlights
+
+- Expands the stack with `wdk-btc-wallet/`, `provider-gateway/`, and `docs/`
+- Keeps `mcp-server/`, `agent-wallet/`, and `.openclaw/extensions/agent-wallet/` as the base beta foundation
+- Beta release intended for testing, onboarding, and early adopters
+
+### Included in this release
+
+#### `wdk-btc-wallet/`
+
+- Local BTC wallet service built on Tether WDK
+- Wallet lifecycle, balances, fee rates, spendability, and transfer support
+- Separate runtime from the existing Solana wallet backend
+
+#### `provider-gateway/`
+
+- Hosted Solana RPC defaults through a shared gateway
+- Bags launch and fees provider access
+- Jupiter Earn provider access
+
+#### `docs/`
+
+- Separate documentation app for setup and architecture reference
+- Covers infrastructure and wallet capability docs
+- Repo-owned docs surface for the public beta
+
+#### `mcp-server/`
+
+- MCP server for crypto, DeFi, and on-chain data workflows
+- Read-oriented market, protocol, gas, and identity tooling
+- Local/self-hostable deployment path
+
+#### `agent-wallet/`
+
+- Local Solana wallet backend for OpenClaw-connected agents
+- Read, preview, prepare, and approved execute flows
+- Encrypted local secret handling and explicit approval gating for risky actions
+
+#### `.openclaw/extensions/agent-wallet/`
+
+- Thin TypeScript bridge from OpenClaw into the Python wallet backend
+- Plugin manifest and config schema tracked in the repo
+- Repo-local extension package for OpenClaw integration
+
+### Beta notes
+
+- This is a beta release and should not be presented as production-ready custody infrastructure
+- Mainnet usage should remain cautious and operator-controlled

package/agent-wallet/.env.example

@@ -0,0 +1,62 @@
+# --- OpenClaw Agent Wallet ---
+
+# Backend selection
+AGENT_WALLET_BACKEND=none
+AGENT_WALLET_SIGN_ONLY=false
+AGENT_WALLET_BOOT_KEY=
+# Runtime secrets are loaded only from ~/.openclaw/sealed_keys.json via AGENT_WALLET_BOOT_KEY.
+# Per-user HKDF derivation and encrypted user-wallet storage are mandatory.
+AGENT_WALLET_PER_USER_KEY_DERIVATION=true
+AGENT_WALLET_ENCRYPT_USER_WALLETS=true
+AGENT_WALLET_MIGRATE_PLAINTEXT_USER_WALLETS=true
+AGENT_WALLET_REFUSE_MAINNET_WALLET_RECREATION=true
+AGENT_WALLET_REQUIRE_ENCRYPTED_MAINNET=true
+AGENT_WALLET_MAX_PER_TX_SOL=0
+AGENT_WALLET_MAX_HOURLY_SOL=0
+AGENT_WALLET_MAX_DAILY_SOL=0
+AGENT_WALLET_MAX_TXS_PER_MINUTE=0
+
+# Solana backend
+SOLANA_NETWORK=mainnet
+SOLANA_RPC_URL=
+SOLANA_RPC_URLS=
+SOLANA_RPC_PROVIDER_MODE=auto
+# Optional deployment shortcut: if SOLANA_RPC_URL(S) are empty, agent-wallet
+# auto-derives a Solana Alchemy or Helius RPC from this key on mainnet/devnet.
+ALCHEMY_API_KEY=
+HELIUS_API_KEY=
+PROVIDER_GATEWAY_URL=https://agent-layer-production.up.railway.app
+PROVIDER_GATEWAY_BEARER_TOKEN=
+PROVIDER_GATEWAY_RPC_PROVIDER=auto
+# Swap routing stays Jupiter-first. Bags is used separately for launch/fees via provider-gateway.
+SOLANA_SWAP_PROVIDER=auto
+SOLANA_COMMITMENT=confirmed
+SOLANA_AUTO_CREATE_WALLET=false
+
+# Read-only mode
+SOLANA_AGENT_PUBLIC_KEY=
+
+# Signing mode: use a sealed `private_key` entry or a file path
+SOLANA_AGENT_KEYPAIR_PATH=
+
+# Jupiter swap routing
+JUPITER_API_BASE_URL=https://lite-api.jup.ag/swap/v1
+JUPITER_ULTRA_API_BASE_URL=https://lite-api.jup.ag/ultra/v1
+JUPITER_PRICE_API_BASE_URL=https://lite-api.jup.ag/price/v3
+JUPITER_PORTFOLIO_API_BASE_URL=https://api.jup.ag/portfolio/v1
+JUPITER_LEND_API_BASE_URL=https://api.jup.ag/lend/v1
+JUPITER_API_KEY=
+
+# LI.FI cross-chain routing. API key is optional for basic read-only quote/status calls.
+# Keep Mayan denied here so LI.FI cannot route through that bridge.
+LIFI_API_BASE_URL=https://li.quest/v1
+LIFI_API_KEY=
+LIFI_INTEGRATOR=openclaw
+LIFI_DEFAULT_DENY_BRIDGES=mayan
+
+# Kamino REST lending
+KAMINO_API_BASE_URL=https://api.kamino.finance
+KAMINO_PROGRAM_ID=KLend2g3cP87fffoy8q1mQqGKjrxjC8boSyAYavgmjD
+
+# Shared HTTP timeout
+HTTP_TIMEOUT=10.0