npm package: @missionsquad/agent-wallet
Description: Universal multi-chain secure signing SDK for AI agents
Author: BankOfAI
Latest version: 1.0.0

# agent-wallet

![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)
![Node.js](https://img.shields.io/badge/Node.js-≥18-339933)

`@missionsquad/agent-wallet` is a TypeScript SDK and CLI for secure wallet-based signing on TRON and EVM chains.

The package is sign-only:

- create or import wallets
- resolve the active wallet
- sign transactions, messages, and typed data
- optionally use hosted adapters such as Privy

It does **not** broadcast transactions for you.

## Install

```bash
npm install @missionsquad/agent-wallet
# or
pnpm add @missionsquad/agent-wallet
```

Install the CLI globally if needed:

```bash
npm install -g @missionsquad/agent-wallet
```

## Quick Start

### SDK

```ts
import { resolveWallet } from "@missionsquad/agent-wallet";

const wallet = await resolveWallet({ network: "tron:nile" });
const signature = await wallet.signMessage(new TextEncoder().encode("hello"));
```

`resolveWallet` automatically uses `~/.agent-wallet` unless `AGENT_WALLET_DIR` is set.

### CLI

Create an encrypted wallet:

```bash
agent-wallet start
```

List wallets:

```bash
agent-wallet list
```

Sign a message:

```bash
agent-wallet sign msg "MESSAGE" -n tron -p 'StrongPassword123!@#'
```

## Wallet Types

| Wallet Type | Source | Networks | Password Required | Notes |
|-------------|--------|----------|-------------------|-------|
| `local_secure` | CLI config | EVM + TRON | Yes | Encrypted on disk; recommended. |
| `raw_secret` | CLI config / env | EVM + TRON | No | Plaintext in config or env; dev only. |
| `privy` | CLI config | EVM + TRON | No | Hosted signing through Privy. |

## Public API

```ts
import {
  resolveWallet,
  resolveWalletProvider,
  ConfigWalletProvider,
  EnvWalletProvider,
  TenantWalletProvider,
} from "@missionsquad/agent-wallet";
```

### `resolveWallet`

Returns a ready-to-sign `Wallet`:

```ts
const wallet = await resolveWallet({ network: "eip155:1" });
const signed = await wallet.signTransaction({ to: "0x...", value: 0 });
```

### `resolveWalletProvider`

Returns either `ConfigWalletProvider` or `EnvWalletProvider` based on local config and environment.

### `TenantWalletProvider`

`TenantWalletProvider` is intended for managed multi-tenant server deployments where each tenant owns one encrypted wallet directory:

```ts
import { TenantWalletProvider } from "@missionsquad/agent-wallet";

const provider = new TenantWalletProvider({
  tenantId: "41...",
  walletDir: "/srv/app/data/tenants/41.../agent-wallet",
  masterPassword: "derived-server-side-password",
  network: "tron",
});

const created = await provider.createPrimaryTronWallet();
```

Design rules:

- one wallet per tenant (`primary`)
- encrypted `local_secure` storage
- no `runtime_secrets.json` required for managed tenant directories

## Environment Variables

| Variable | Description |
|---|---|
| `AGENT_WALLET_DIR` | Wallet directory (default `~/.agent-wallet`) |
| `AGENT_WALLET_PASSWORD` | Password for `local_secure` wallets |
| `AGENT_WALLET_PRIVATE_KEY` | Env fallback private key |
| `AGENT_WALLET_MNEMONIC` | Env fallback mnemonic |
| `AGENT_WALLET_MNEMONIC_ACCOUNT_INDEX` | Mnemonic derivation index |

## Examples

- [TRON sign & broadcast](./examples/tron-sign-and-broadcast.ts)
- [BSC sign & broadcast](./examples/bsc-sign-and-broadcast.ts)
- [Switch active wallet](./examples/switch-active-wallet.ts)
- [TRON x402 typed data](./examples/tron-x402-sign-typed-data.ts)
- [BSC x402 typed data](./examples/bsc-x402-sign-typed-data.ts)
- [Dual-sign typed data from private key](./examples/dual-sign-typed-data-from-private-key.ts)
- [Privy sign consistency](./examples/compare-sign-consistency.ts)
- [Verify TRON Privy typed-data](./examples/verify-tron-privy-typed-data.ts)

## Documentation

- [Getting started](./doc/getting-started.md)
- [How to add a Privy wallet](./doc/how-to-add-privy-wallet.md)

## Development

```bash
pnpm install
pnpm test
pnpm build
```

## License

[MIT](./LICENSE)