@agentlayer.tech/wallet 0.1.0

package/agent-wallet/examples/bootstrap_wallet.py

@@ -0,0 +1,21 @@
+"""Example bootstrap entrypoint for OpenClaw plugin startup."""
+
+from __future__ import annotations
+
+import json
+
+from agent_wallet.bootstrap import describe_bootstrap, ensure_solana_wallet_ready
+
+
+def main() -> None:
+    print("Bootstrap configuration:")
+    print(json.dumps(describe_bootstrap(), indent=2))
+    print()
+
+    result = ensure_solana_wallet_ready()
+    print("Bootstrap result:")
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/agent-wallet/examples/openclaw_runtime_onboarding.py

@@ -0,0 +1,28 @@
+"""Example: host-side onboarding flow for attaching agent-wallet to OpenClaw."""
+
+from __future__ import annotations
+
+import json
+
+from agent_wallet.openclaw_runtime import onboard_openclaw_user_wallet
+
+
+def main() -> None:
+    user_id = "demo-user-123"
+    # Set AGENT_WALLET_MASTER_KEY in the environment before first run.
+    context = onboard_openclaw_user_wallet(
+        user_id,
+        sign_only=False,
+        network="devnet",
+    )
+
+    print("Session metadata:")
+    print(context.session_metadata().model_dump_json(indent=2))
+    print()
+
+    print("Serializable bundle for OpenClaw runtime:")
+    print(json.dumps(context.serializable_bundle(), indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/agent-wallet/examples/openclaw_user_wallet_example.py

@@ -0,0 +1,31 @@
+"""Example: user-scoped wallet integration for an OpenClaw runtime."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from agent_wallet.openclaw_adapter import OpenClawWalletAdapter
+from agent_wallet.user_wallets import create_wallet_backend_for_user
+
+
+async def main() -> None:
+    user_id = "demo-user-123"
+    # Set AGENT_WALLET_MASTER_KEY in the environment before first run so
+    # the per-user wallet is encrypted at rest.
+    backend = create_wallet_backend_for_user(
+        user_id,
+        sign_only=False,
+        network="devnet",
+    )
+    adapter = OpenClawWalletAdapter(backend)
+
+    print(f"Loaded backend for user_id={user_id}")
+    print(json.dumps([tool.model_dump() for tool in adapter.list_tools()], indent=2))
+
+    address = await adapter.invoke("get_wallet_address")
+    print(address.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/agent-wallet/examples/openclaw_wallet_adapter_example.py

@@ -0,0 +1,33 @@
+"""Example: exposing agent-wallet tools to an OpenClaw-style runtime."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+
+from agent_wallet.openclaw_adapter import OpenClawWalletAdapter
+from agent_wallet.wallet_layer.factory import create_wallet_backend
+
+
+async def main() -> None:
+    backend = create_wallet_backend()
+    if backend is None:
+        raise RuntimeError("No wallet backend configured. Set AGENT_WALLET_BACKEND first.")
+
+    adapter = OpenClawWalletAdapter(backend)
+
+    print("Runtime instructions:")
+    print(adapter.get_runtime_instructions())
+    print()
+
+    print("Registered tools:")
+    print(json.dumps([tool.model_dump() for tool in adapter.list_tools()], indent=2))
+    print()
+
+    result = await adapter.invoke("get_wallet_capabilities")
+    print("Capabilities:")
+    print(result.model_dump_json(indent=2))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

package/agent-wallet/openclaw.plugin.json

@@ -0,0 +1,138 @@
+{
+  "id": "agent-wallet",
+  "name": "Agent Wallet",
+  "description": "Plugin-friendly wallet backend for OpenClaw agents with safe wallet tools and runtime instructions across Solana, local BTC, and local EVM.",
+  "version": "0.1.0",
+  "skills": ["skills/wallet-operator"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "backend": {
+        "type": "string",
+        "description": "Wallet backend identifier. Supported values: solana_local, wdk_btc_local, wdk_evm_local."
+      },
+      "rpcUrl": {
+        "type": "string",
+        "description": "Optional local fallback Solana RPC URL. Deployment env SOLANA_RPC_URL wins if set."
+      },
+      "rpcUrls": {
+        "type": "array",
+        "items": { "type": "string" },
+        "description": "Optional local fallback ordered list of Solana RPC URLs. Deployment env SOLANA_RPC_URLS wins if set."
+      },
+      "rpcProviderMode": {
+        "type": "string",
+        "description": "RPC mode: auto, user_direct, or shared_proxy. In auto mode, user RPC keys/URLs win; otherwise the shared provider gateway is used when configured."
+      },
+      "providerGatewayUrl": {
+        "type": "string",
+        "description": "Optional override for the shared provider gateway base URL. If omitted, the hosted OpenClaw gateway default is used for onboarding-friendly mainnet RPC and Bags launch/fees flows."
+      },
+      "providerGatewayRpcProvider": {
+        "type": "string",
+        "description": "Optional shared RPC upstream selection for the provider gateway: auto, shared, helius, or alchemy."
+      },
+      "swapProvider": {
+        "type": "string",
+        "description": "Optional Solana swap routing preference: auto or jupiter. Bags launch and fee flows still use the provider gateway separately, but token swaps stay Jupiter-first."
+      },
+      "network": {
+        "type": "string",
+        "description": "Backend network selector. Solana uses mainnet/devnet/testnet. BTC uses bitcoin/testnet/regtest. EVM uses ethereum/sepolia/base/base-sepolia."
+      },
+      "wdkBtcServiceUrl": {
+        "type": "string",
+        "description": "Base URL for the localhost-only wdk-btc-wallet HTTP service when backend=wdk_btc_local."
+      },
+      "wdkBtcWalletId": {
+        "type": "string",
+        "description": "Optional direct walletId override from the local wdk-btc-wallet vault. If omitted, agent-wallet will look for a user-bound BTC wallet under ~/.openclaw/users/<user>/wallets/."
+      },
+      "wdkBtcAccountIndex": {
+        "type": "integer",
+        "description": "Optional BTC account index to expose to the agent. Defaults to 0."
+      },
+      "wdkEvmServiceUrl": {
+        "type": "string",
+        "description": "Base URL for the localhost-only wdk-evm-wallet HTTP service when backend=wdk_evm_local."
+      },
+      "wdkEvmWalletId": {
+        "type": "string",
+        "description": "Optional direct walletId override from the local wdk-evm-wallet vault. If omitted, agent-wallet will look for a user-bound EVM wallet under ~/.openclaw/users/<user>/wallets/."
+      },
+      "wdkEvmAccountIndex": {
+        "type": "integer",
+        "description": "Optional EVM account index to expose to the agent. Defaults to 0."
+      },
+      "publicKey": {
+        "type": "string",
+        "description": "Read-only wallet public key."
+      },
+      "privateKey": {
+        "type": "string",
+        "description": "Deprecated insecure config path. Inject signing key material via environment variables instead of plugin config."
+      },
+      "keypairPath": {
+        "type": "string",
+        "description": "Path to Solana CLI JSON keypair file."
+      },
+      "autoCreateWallet": {
+        "type": "boolean",
+        "description": "Create a local wallet file automatically on first start if none exists."
+      },
+      "signOnly": {
+        "type": "boolean",
+        "description": "If true, the wallet may sign but should not broadcast transactions automatically."
+      },
+      "masterKey": {
+        "type": "string",
+        "description": "Deprecated insecure config path. Inject the wallet master secret via environment or a secret manager instead of plugin config."
+      },
+      "approvalSecret": {
+        "type": "string",
+        "description": "Deprecated insecure config path. Inject the approval secret via environment or a secret manager instead of plugin config."
+      },
+      "encryptUserWallets": {
+        "type": "boolean",
+        "description": "If true, newly created per-user wallet files are encrypted at rest."
+      },
+      "refuseMainnetWalletRecreation": {
+        "type": "boolean",
+        "description": "If true, refuse to silently create a new mainnet wallet when a pinned address already exists."
+      },
+      "jupiterBaseUrl": {
+        "type": "string",
+        "description": "Optional Jupiter Swap API base URL for quote and swap building."
+      },
+      "jupiterUltraBaseUrl": {
+        "type": "string",
+        "description": "Optional Jupiter Ultra API base URL for managed swap execution."
+      },
+      "jupiterPriceBaseUrl": {
+        "type": "string",
+        "description": "Optional Jupiter Price API base URL for token price lookup."
+      },
+      "jupiterPortfolioBaseUrl": {
+        "type": "string",
+        "description": "Optional Jupiter Portfolio API base URL for Jupiter-specific positions and staking data."
+      },
+      "jupiterLendBaseUrl": {
+        "type": "string",
+        "description": "Optional Jupiter Lend API base URL for Earn read and deposit/withdraw flows."
+      },
+      "jupiterApiKey": {
+        "type": "string",
+        "description": "Optional Jupiter API key if your deployment uses a keyed endpoint."
+      },
+      "kaminoBaseUrl": {
+        "type": "string",
+        "description": "Optional Kamino REST API base URL for lending reads and transaction building."
+      },
+      "kaminoProgramId": {
+        "type": "string",
+        "description": "Optional Kamino lending program id for market discovery."
+      }
+    }
+  }
+}

package/agent-wallet/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "openclaw-agent-wallet"
+version = "0.1.0"
+description = "Plugin-friendly wallet backend for OpenClaw agents"
+requires-python = ">=3.11"
+dependencies = [
+    "httpx>=0.27.0",
+    "pydantic>=2.0.0",
+    "pydantic-settings>=2.0.0",
+    "pynacl>=1.5.0",
+    "python-dotenv>=1.0.0",
+    "solana>=0.36.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "ruff>=0.4.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["agent_wallet"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100

package/agent-wallet/scripts/bootstrap_openclaw_btc.py

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""One-command host bootstrap for the local OpenClaw BTC wallet flow."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import sys
+import time
+from urllib.error import URLError
+from urllib.parse import urlparse
+from urllib.request import urlopen
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from agent_wallet.file_ops import atomic_write_text, chmod_if_exists
+
+
+def _default_config_path() -> Path:
+    return Path(os.path.expanduser("~/.openclaw/openclaw.json"))
+
+
+def _default_user_id() -> str:
+    return f"{os.getenv('USER', 'openclaw-user')}-local"
+
+
+def _default_python_bin() -> str:
+    return os.getenv("OPENCLAW_AGENT_WALLET_PYTHON", sys.executable)
+
+
+def _package_root() -> Path:
+    return Path(__file__).resolve().parents[1]
+
+
+def _repo_root() -> Path:
+    return Path(__file__).resolve().parents[2]
+
+
+def _script_path(name: str) -> Path:
+    return _package_root() / "scripts" / name
+
+
+def _normalize_network(value: str) -> str:
+    network = str(value or "").strip().lower()
+    if network == "mainnet":
+        return "bitcoin"
+    return network or "bitcoin"
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config-path", default=str(_default_config_path()))
+    parser.add_argument("--plugin-id", default="agent-wallet")
+    parser.add_argument("--user-id", default=_default_user_id())
+    parser.add_argument("--network", default="testnet")
+    parser.add_argument("--service-url", default="http://127.0.0.1:8080")
+    parser.add_argument("--wdk-wallet-root", default=str(_repo_root() / "wdk-btc-wallet"))
+    parser.add_argument("--label", default="Agent BTC Wallet")
+    parser.add_argument("--account-index", type=int, default=0)
+    parser.add_argument("--python-bin", default=_default_python_bin())
+    parser.add_argument("--package-root", default=str(_package_root()))
+    parser.add_argument("--password-stdin", action=argparse.BooleanOptionalAction, default=False)
+    parser.add_argument("--reveal-seed", action=argparse.BooleanOptionalAction, default=False)
+    parser.add_argument("--sign-only", action=argparse.BooleanOptionalAction, default=False)
+    parser.add_argument("--auto-start-service", action=argparse.BooleanOptionalAction, default=True)
+    return parser
+
+
+def _ensure_openclaw_config(config_path: Path) -> bool:
+    if config_path.exists():
+        return False
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    atomic_write_text(
+        config_path,
+        json.dumps({"plugins": {"entries": {}}, "tools": {"alsoAllow": []}}, indent=2) + "\n",
+        mode=0o600,
+    )
+    chmod_if_exists(config_path, 0o600)
+    return True
+
+
+def _run_script(
+    python_bin: str,
+    script_name: str,
+    args: list[str],
+    *,
+    stdin_text: str | None = None,
+) -> dict:
+    completed = subprocess.run(
+        [python_bin, str(_script_path(script_name)), *args],
+        check=True,
+        capture_output=True,
+        text=True,
+        input=stdin_text,
+        env=os.environ.copy(),
+    )
+    return json.loads(completed.stdout)
+
+
+def _health_url(service_url: str) -> str:
+    return f"{service_url.rstrip('/')}/health"
+
+
+def _service_is_healthy(service_url: str) -> bool:
+    try:
+        with urlopen(_health_url(service_url), timeout=1.5) as response:
+            return int(getattr(response, "status", 0) or 0) == 200
+    except (URLError, TimeoutError, OSError):
+        return False
+
+
+def _is_local_service_url(service_url: str) -> bool:
+    parsed = urlparse(service_url)
+    return parsed.scheme in {"http", "https"} and parsed.hostname in {"127.0.0.1", "localhost", "::1"}
+
+
+def _require_local_service_url(service_url: str) -> None:
+    if not _is_local_service_url(service_url):
+        raise SystemExit(
+            f"BTC bootstrap only supports a localhost service URL. Refusing non-local endpoint: {service_url}"
+        )
+
+
+def _service_log_dir(config_path: Path) -> Path:
+    return config_path.expanduser().parent / "logs"
+
+
+def _service_log_path(config_path: Path) -> Path:
+    return _service_log_dir(config_path) / "wdk-btc-wallet.log"
+
+
+def _auto_start_local_service(
+    *,
+    service_url: str,
+    network: str,
+    wdk_wallet_root: Path,
+    config_path: Path,
+) -> dict[str, object]:
+    if _service_is_healthy(service_url):
+        return {"started": False, "already_healthy": True}
+
+    if not _is_local_service_url(service_url):
+        raise SystemExit(
+            f"BTC service at {service_url} is unreachable and auto-start is only supported for localhost URLs."
+        )
+
+    run_local = wdk_wallet_root / "run-local.sh"
+    if not run_local.exists():
+        raise SystemExit(f"Could not find wdk-btc-wallet launcher: {run_local}")
+
+    parsed = urlparse(service_url)
+    host = parsed.hostname or "127.0.0.1"
+    port = parsed.port or 8080
+    log_dir = _service_log_dir(config_path)
+    log_dir.mkdir(parents=True, exist_ok=True)
+    log_path = _service_log_path(config_path)
+
+    env = os.environ.copy()
+    env["HOST"] = host
+    env["PORT"] = str(port)
+    env["WDK_BTC_NETWORK"] = network
+
+    with log_path.open("a", encoding="utf-8") as log_file:
+        process = subprocess.Popen(  # noqa: S603
+            ["sh", str(run_local)],
+            cwd=str(wdk_wallet_root),
+            env=env,
+            stdin=subprocess.DEVNULL,
+            stdout=log_file,
+            stderr=log_file,
+            start_new_session=True,
+        )
+
+    deadline = time.time() + 30.0
+    while time.time() < deadline:
+        if _service_is_healthy(service_url):
+            return {
+                "started": True,
+                "already_healthy": False,
+                "pid": process.pid,
+                "log_path": str(log_path),
+            }
+        if process.poll() is not None:
+            raise SystemExit(
+                f"wdk-btc-wallet exited before becoming healthy. Check log: {log_path}"
+            )
+        time.sleep(0.5)
+
+    raise SystemExit(
+        f"Timed out waiting for wdk-btc-wallet health at {_health_url(service_url)}. Check log: {log_path}"
+    )
+
+
+def main() -> int:
+    args = build_parser().parse_args()
+    effective_network = _normalize_network(args.network)
+    _require_local_service_url(args.service_url)
+    config_path = Path(args.config_path).expanduser()
+    config_created = _ensure_openclaw_config(config_path)
+    service_bootstrap: dict[str, object] | None = None
+    if args.auto_start_service:
+        service_bootstrap = _auto_start_local_service(
+            service_url=args.service_url,
+            network=effective_network,
+            wdk_wallet_root=Path(args.wdk_wallet_root).expanduser(),
+            config_path=config_path,
+        )
+    elif not _service_is_healthy(args.service_url):
+        raise SystemExit(
+            f"BTC service is not healthy at {_health_url(args.service_url)} and --no-auto-start-service was set."
+        )
+
+    stdin_text = sys.stdin.read() if args.password_stdin else None
+    setup_payload = _run_script(
+        args.python_bin,
+        "manage_openclaw_btc_wallet.py",
+        [
+            "setup",
+            "--user-id",
+            args.user_id,
+            "--network",
+            effective_network,
+            "--service-url",
+            args.service_url,
+            "--label",
+            args.label,
+            "--account-index",
+            str(args.account_index),
+            *([] if not args.password_stdin else ["--password-stdin"]),
+            *(["--reveal-seed"] if args.reveal_seed else []),
+        ],
+        stdin_text=stdin_text,
+    )
+
+    install_args = [
+        "--config-path",
+        str(config_path),
+        "--plugin-id",
+        args.plugin_id,
+        "--user-id",
+        args.user_id,
+        "--backend",
+        "wdk_btc_local",
+        "--network",
+        effective_network,
+        "--wdk-btc-service-url",
+        args.service_url,
+        "--wdk-btc-account-index",
+        str(args.account_index),
+        "--package-root",
+        args.package_root,
+        "--python-bin",
+        args.python_bin,
+        "--sign-only" if args.sign_only else "--no-sign-only",
+    ]
+    install_payload = _run_script(
+        args.python_bin,
+        "install_openclaw_local_config.py",
+        install_args,
+    )
+
+    output = {
+        "ok": True,
+        "config_created": config_created,
+        "config_path": str(config_path),
+        "service_bootstrap": service_bootstrap,
+        "btc_setup": setup_payload,
+        "openclaw_config": install_payload,
+    }
+    print(json.dumps(output, indent=2))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())