# mcp-wallet

Chain-agnostic MCP wallet interface for durable AI agents with autonomous transfers.

The durable agent runtime is the wallet principal: it can create wallets and independently simulate, inspect, revalidate, sign, and broadcast supported transactions. Mnemonics and private keys remain inside encrypted local custody rather than crossing the model context.

## Supported addresses

| Chain | Derivation path | Address type |
|---|---|---|
| Bitcoin | `m/84'/0'/0'/0/0` | Mainnet P2WPKH (Bech32) |
| Ethereum | `m/44'/60'/0'/0/0` | EIP-55 EVM address |
| BNB Smart Chain | `m/44'/60'/0'/0/0` | Same EVM address |
| Solana | `m/44'/501'/0'/0'` | Base58 ed25519 public key |
| TRON | `m/44'/195'/0'/0/0` | Base58Check account address |
| HyperEVM | `m/44'/60'/0'/0/0` | Same EVM address |
| HyperCore | `m/44'/60'/0'/0/0` | Same EVM account identity |

## Current scope

- Create and import accounts
- List accounts and derived addresses
- Show or delete an account
- AES-256-GCM encrypted mnemonic storage
- Agent-owned wallet creation through local MCP without exposing the mnemonic
- Native balance reads and two-step native Ethereum, BNB Smart Chain, and HyperEVM transactions to ordinary code-less recipients outside reserved precompile/system address space; successful simulation must return empty call data
- Mandatory exact-transaction preflight with deterministic outflow reports and execution-time revalidation
- CAIP-2 chain identifiers and runtime capability discovery through a typed transaction interface
- Optional agent-configured policy safeguards; no mandatory human approval
- Local stdio MCP transport with no listening network port
- Chain-adapter boundary for future extensions

Not implemented: tokens, calldata, contract calls, swaps, bridges, Bitcoin/Solana/TRON transfers, HyperCore actions, indexed history, or automatic testnet selection.

## Setup

Requirements: Linux with the util-linux `flock` command, and Node.js 22 or newer. Wallet and transfer state use kernel-managed advisory locks so crashes cannot leave stale ownership metadata or permit PID-reuse/ABA lock races.

```bash
npm install
npm run build
```

Generate a development master key without printing it:

```bash
export CRYPTO_MCP_MASTER_KEY="$(node -e "process.stdout.write(require('node:crypto').randomBytes(32).toString('base64'))")"
```

Optional wallet-file override:

```bash
export CRYPTO_MCP_WALLET_FILE="$HOME/.crypto-mcp/wallet.json"
```

The default wallet file is `$HOME/.crypto-mcp/wallet.json` and is written with mode `0600`.

## Maintenance CLI

Create an account:

```bash
npm run wallet -- account create --label primary
```

The generated mnemonic is printed exactly once. Transfer it immediately to an appropriate offline backup or password manager; do not place it in shell history, logs, chat, source control, or MCP requests.

Import from stdin:

```bash
password-manager-command | npm run wallet -- account import --label imported
```

Manage public account data:

```bash
npm run wallet -- account list
npm run wallet -- account show <account-id>
npm run wallet -- account delete <account-id>
```

The CLI retains explicit lifecycle commands for debugging, recovery, and manual maintenance, but it is not part of the agent's authorization path:

```bash
npm run wallet -- transfer status <request-id>
npm run wallet -- transfer approve <request-id> --digest sha256:<digest>
npm run wallet -- transfer sign <request-id>
npm run wallet -- transfer broadcast <request-id>
```

Approval is bound to the account, chain ID, recipient, raw amount, nonce, fee fields, expiry, idempotency key, pinned simulation block, canonical outflows, completeness, and deterministic summary. Execution rechecks the pending nonce before and after exact re-simulation, then custody authenticates fresh evidence before signing. Signing and first submission reject stale, forged, or incomplete authorization.

## Agent wallet MCP server

The local stdio server exposes exactly nine tools:

- `create_wallet`
- `list_accounts`
- `get_account`
- `get_addresses`
- `get_wallet_capabilities`
- `get_balance`
- `simulate_transaction`
- `execute_transaction`
- `get_transaction_status`

Start it with process-local wallet configuration:

```bash
npm run build
npm run mcp
```

An MCP client should launch `node /absolute/path/to/mcp-wallet/dist/src/mcp/stdio.js` and provide `CRYPTO_MCP_MASTER_KEY` and, optionally, `CRYPTO_MCP_WALLET_FILE` to that subprocess through external secret injection. Never put the master key in tool arguments, prompts, chat, source control, or ordinary configuration files.

`create_wallet` generates an encrypted wallet without returning its mnemonic. `get_wallet_capabilities` advertises the exact configured chains, assets, and operations. `get_balance` and `simulate_transaction` use CAIP-2 chain identifiers such as `eip155:1` plus an explicit typed operation; the current adapter supports only native transfers. `simulate_transaction` reserves the exact nonce, prepares exact fee and gas fields, pins an RPC block, runs `eth_call`, and returns canonical wallet outflows plus a bounded deterministic summary. `execute_transaction` accepts only that simulation ID and digest, rechecks the configured chain and policy, re-simulates the exact transaction at fresh chain state, and signs and broadcasts only if the preflight remains valid. Generic tool names do not imply unsupported-chain support: unadvertised chains, assets, and operations fail closed. MCP cannot supply RPC URLs, policy overrides, nonces, calldata, raw signing payloads, mnemonics, or private keys, and sanitized results never expose raw signed transactions.

## Transfer configuration

Each configured network defaults to full agent authority. Configure the owner-only transfer journal and RPC details in the MCP process environment—not tool arguments:

```bash
export CRYPTO_MCP_TRANSFER_FILE="$HOME/.crypto-mcp/transfers.json"
export CRYPTO_MCP_ETHEREUM_RPC_URL="https://your-rpc.example"
export CRYPTO_MCP_ETHEREUM_CHAIN_ID="1"
export CRYPTO_MCP_ETHEREUM_FEE_MODE="eip1559"
```

Equivalent `BSC` and `HYPEREVM` variables are supported. Fee mode must be `eip1559` or `legacy`; chain ID is verified against `eth_chainId` before preparation. Use disposable accounts, test networks, bounded policy values, and non-production funds for initial validation.

An agent may opt into self-imposed safeguards by setting `CRYPTO_MCP_TRANSFER_POLICY`. Providing it switches to explicit policy configuration; omitted chains are disabled. Policies can set amount, fee, rolling 24-hour value, account, and recipient bounds. These are optional wallet-owner controls, not human approval requirements.

## MCP usage examples

These are MCP tool arguments and structured results, not shell commands. Start the stdio server with process-local custody and network configuration before invoking transfer tools.

### Create an agent-owned wallet

Tool: `create_wallet`

```json
{
  "label": "primary-agent-wallet"
}
```

The result contains the account ID, label, creation time, and public addresses. It never contains the generated mnemonic or private keys.

### Discover supported chains and assets

Tool: `get_wallet_capabilities`

```json
{}
```

Example result for a configured Ethereum network:

```json
{
  "chains": [
    {
      "chain": "eip155:1",
      "family": "evm",
      "assets": [{ "asset": "native", "decimals": 18 }],
      "operations": ["get_balance", "simulate_transaction", "execute_transaction", "get_transaction_status"],
      "transactionTypes": ["transfer"],
      "contractRecipients": false,
      "preflight": {
        "required": true,
        "completeness": "complete",
        "executionRevalidation": true
      }
    }
  ]
}
```

Only advertised chain and asset combinations are supported. For example, a configured Sepolia network is identified as `eip155:11155111`.

### Read a balance

Tool: `get_balance`

```json
{
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "asset": "native"
}
```

Example result:

```json
{
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "asset": "native",
  "address": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
  "balance": "1.25",
  "balanceBaseUnits": "1250000000000000000",
  "decimals": 18
}
```

All amounts are decimal strings. Base-unit values are exact integer strings and are never converted through JavaScript floating point.

### Simulate a transaction

Tool: `simulate_transaction`

```json
{
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "operation": {
    "type": "transfer",
    "asset": "native",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "amount": "0.001"
  },
  "maxFee": "0.0002",
  "idempotencyKey": "pay-invoice-2026-08-07-001"
}
```

The wallet validates policy and balances, reserves the nonce, constructs the exact unsigned transaction, and simulates it at a pinned block. Reusing the same idempotency key with the same request converges on the existing transaction; changing any request field fails closed.

Example result:

```json
{
  "requestId": "0190f502-f56d-7000-8000-000000000001",
  "state": "simulated",
  "accountId": "0190f4f6-7f08-7000-8000-000000000001",
  "chain": "eip155:1",
  "operation": {
    "type": "transfer",
    "asset": "native",
    "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
    "amount": "0.001",
    "amountBaseUnits": "1000000000000000"
  },
  "maxFeeBaseUnits": "200000000000000",
  "createdAt": "2026-08-07T00:00:00.000Z",
  "expiresAt": "2026-08-07T00:05:00.000Z",
  "preflight": {
    "simulationId": "0190f502-f56d-7000-8000-000000000001",
    "intentDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000",
    "status": "succeeded",
    "simulatedAt": "2026-08-07T00:00:00.000Z",
    "blockReference": "21900421",
    "blockHash": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
    "blockTimestamp": "1786060800",
    "simulationCompleteness": "complete",
    "summary": "Send 0.001 native asset units from 0x9858EfFD232B4033E47d90003D41EC34EcaEda94 to 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045 on eip155:1. Maximum network fee: 0.000105 native asset units.",
    "outflows": [
      {
        "kind": "transfer",
        "from": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
        "to": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
        "asset": "native",
        "amount": "0.001",
        "amountBaseUnits": "1000000000000000",
        "certainty": "exact"
      },
      {
        "kind": "network_fee",
        "from": "0x9858EfFD232B4033E47d90003D41EC34EcaEda94",
        "to": "network",
        "asset": "native",
        "amount": "0.000105",
        "amountBaseUnits": "105000000000000",
        "certainty": "maximum"
      }
    ],
    "warnings": []
  }
}
```

The summary is generated deterministically from the same canonical fields as `outflows`. `simulationCompleteness: "complete"` applies only to the currently supported native-transfer operation; it is not a claim that arbitrary contract effects can be inferred from `eth_call`.

### Execute the reviewed simulation

Tool: `execute_transaction`

```json
{
  "simulationId": "0190f502-f56d-7000-8000-000000000001",
  "intentDigest": "sha256:0000000000000000000000000000000000000000000000000000000000000000"
}
```

The digest binds the exact prepared transaction and preflight report, including the pinned block number, hash, and timestamp. Before signing, the wallet checks expiry, account and chain configuration, policy, and RPC chain ID, rejects block metadata more than 120 seconds old or more than 15 seconds in the future, then re-simulates the exact transaction at fresh pinned state. A missing, stale, reverted, malformed, incomplete, or digest-mismatched preflight fails closed. A successful result preserves the preflight, adds `revalidatedAt`, `revalidationBlockReference`, `revalidationBlockHash`, and `revalidationBlockTimestamp`, and eventually includes `transactionId` after signing and broadcast.

### Check transaction status

Tool: `get_transaction_status`

```json
{
  "requestId": "0190f502-f56d-7000-8000-000000000001"
}
```

The result uses the same transaction shape. A prepared report is exposed as `state: "simulated"`; a confirmed transaction may also include `blockReference`; a terminal failure may include a bounded `failureCode`.

## Development

```bash
npm run typecheck
npm test
```

The test suite derives its public BIP-39 vector from fixed entropy rather than storing a mnemonic phrase in repository fixtures.

## Library API

```ts
import { JsonAccountStore, WalletAccountService } from "crypto-mcp";

const service = new WalletAccountService(
  new JsonAccountStore(walletFile),
  masterKey,
);

const accounts = await service.listAccounts();
```

MCP wallet creation and execution are autonomous: an agent can inspect the deterministic preflight and submit its digest without routine human approval. Secret import/export remains outside model-visible tools; MCP never accepts or returns mnemonics, seeds, private keys, master keys, or raw signed transactions.

See [docs/security.md](docs/security.md) for the custody boundary and current limitations.