@talken/agentic-wallet

Multi-chain MPC wallet for AI agents — API client, CLI, and MCP server in one package.

Private keys are never exposed to the client. All signing operations use ABC WaaS MPC (Multi-Party Computation) — key shares are split across the user device and HSM-backed servers so that no single party holds the complete key. Token swaps, cross-chain bridges (LZ / CCTP), gasless relay, staking, Hyperliquid perp/spot trading, Polymarket prediction markets, and agent sessions are supported. All calls route through talken-api (single endpoint).

Install

# Global install (recommended)
npm install -g @talken/agentic-wallet
talken --help

# Run without installing
npx -y --package=@talken/agentic-wallet talken --help

# As a library (Telegram bot, backend, etc.)
npm install @talken/agentic-wallet

Node 20+ is required.

Quick Start

API Client (Library)

import { TalkenApiClient } from '@talken/agentic-wallet';

const client = new TalkenApiClient('https://api.talken.io/api/v1');
client.setAccessKey('talken_live_<publicId>.<secret>');

// Get balances
const balances = await client.tokenBalances({ chainKey: 'arbitrum', walletAddress: '0x...' });

// Quote a swap
const quote = await client.quote({ chainKey: 'arbitrum', tokenIn: 'ETH', tokenOut: 'USDC', amountIn: '0.1' });

// Sign personal message (EIP-191)
const sig = await client.walletSignPersonal({ network: 'ethereum', message: 'Hello' });

CLI

# First-time setup
talken otp --email <EMAIL> --action send
talken signup --email <EMAIL> --otp <CODE>
talken whoami --full

# Returning user
talken access-key:login --key "talken_live_<publicId>.<secret>"

Claude Code (Slash Command)

The package ships a /talken slash command for Claude Code.

# One-time setup: copy the bundled command to your global Claude commands
npx -y --package=@talken/agentic-wallet talken setup-claude
# or manually:
mkdir -p ~/.claude/commands && cp $(npm root -g)/@talken/agentic-wallet/commands/talken.md ~/.claude/commands/

Then in any Claude Code session:

/talken check my USDC balance on arbitrum
/talken send 5 USDC to 0x... on base
/talken buy 0.01 ETH perp on HL with 5x leverage

MCP Server (Claude Desktop / Cursor)

talken-mcp

Development Setup

git clone https://github.com/talken-io/talken-agentic-wallet.git
cd talken-agentic-wallet
npm install
cp .env.example .env

# .env
TALKEN_API_URL=https://api.talken.io/api/v1  # required
X402_SIGNING_SECRET=<your-secret>             # optional

# Dev mode (tsx)
npm run cli:talken -- <command> [options]

# Build + link
npm run build && npm link
talken <command> [options]

First-time user (dev mode)

npm run cli:talken -- otp --email <EMAIL> --action send
npm run cli:talken -- signup --email <EMAIL> --otp <CODE>
npm run cli:talken -- access-key:login --key "talken_live_<publicId>.<secret>"
npm run cli:talken -- whoami --full

signup auto-generates password/PIN, creates EVM+BTC+TRX+SOL wallets, and issues a default access key.

Commands

| Category | Commands | | -------- | -------- | | Auth | signup (su), otp, login (li), whoami, withdraw, withdraw-status, access-key:login | | Wallet | wallet (w), addr (a), scan (sc), balance (bal), gas (g), nonce (nc), sign (sg), raw (rw) | | Quote / TX | quote (q), build (b), build-from-quote, relay (r), preflight (pf), tx-wait, swap, delegate-eip7702, revoke-eip7702 | | Transfer | send (sd), tx-sol, tx-btc, tx-tvm | | Token | tokens (tk), prices (pr), search (s), approve (apv), allowance (alw), config-tokens, token-caps | | Relay | relay-balance, fee-estimate | | Staking | stake (st), unstake (us), claim (cl), stake-info (si), staking-rewards (rewards) | | Hyperliquid | hl:markets, hl:orderbook, hl:order, hl:sign-order, hl:status, hl:process, hl:cancel, hl:cancel-all, hl:close, hl:trigger, hl:transfer, hl:withdraw, hl:usd-send, hl:spot-send, hl:balance, hl:spot-balance, hl:positions, hl:orders, hl:trades, hl:leverage, hl:fund | | Polymarket | pm:markets, pm:orderbook, pm:positions, pm:orders, pm:orders:live, pm:fills, pm:status, pm:sign-order, pm:order, pm:preflight, pm:cancel, pm:balance, pm:redeem, pm:merge, pm:split, pm:api-key, pm:api-key-local, pm:api-key-local:show, pm:api-key-local:delete, pm:api-key-local:export-env | | Config | chains (ch), tx-status (ts), bridge-status (bs), history (hist) | | Session | session (ss) | | x402 | x402 | | Other | env |

Key options (send)

talken send --chain arbitrum --token USDC --amount 5 --to 0xRecipient
talken send --chain arbitrum --token native --amount 0.001 --to 0xRecipient
talken send --chain arbitrum --token USDC --amount 5 --to 0xRecipient --gasless

Key options (approve)

talken approve --chain arbitrum --token 0x...USDC --spender 0x...Router

Key options (build)

talken build --body '{"action":"swap","chainKey":"arbitrum",...}' --deadline-seconds 600

Polymarket CLOB Key Management

Polymarket CLOB API keys are stored locally at ~/.talken/polymarket-keys.json (chmod 0600).

talken pm:api-key                                    # Acquire key (auto-sign via access key)
talken pm:api-key-local                              # List stored keys
talken pm:api-key-local:show --maker 0x...           # Show key detail
talken pm:api-key-local:export-env --maker 0x...     # Export as env vars
talken pm:api-key-local:delete --maker 0x...         # Delete key

Once a key is stored locally, pm:order and pm:cancel use it automatically for CLOB auth via local HMAC.

MCP Server

95 tools via @modelcontextprotocol/sdk (stdio transport). See skills.md for full tool reference.

# After global install
talken-mcp

# Dev mode
npm run mcp

Claude Desktop config

{
  "mcpServers": {
    "talken-wallet": {
      "command": "talken-mcp",
      "env": { "TALKEN_API_URL": "https://api.talken.io/api/v1" }
    }
  }
}

npx (no install)

{
  "mcpServers": {
    "talken-wallet": {
      "command": "npx",
      "args": ["-y", "--package=@talken/agentic-wallet", "--", "talken-mcp"],
      "env": { "TALKEN_API_URL": "https://api.talken.io/api/v1" }
    }
  }
}

Package Exports

// API client (default export)
import { TalkenApiClient } from '@talken/agentic-wallet';

// Types
import type { RelayExecuteBody } from '@talken/agentic-wallet';

| Entry | Path | Usage | | ------------------------- | ---------------------- | -------------- | | @talken/agentic-wallet | dist/client/index.js | Library import | | talken (bin) | dist/cli/talken.js | CLI | | talken-mcp (bin) | dist/mcp/server.js | MCP server |

Architecture

@talken/agentic-wallet (npm package)
  ├── TalkenApiClient  ← library import (Telegram bot, backend, etc.)
  ├── CLI (109 commands) ← talken <command>
  ├── Slash Command (/talken) ← Claude Code
  └── MCP Server (95 tools) ← talken-mcp
      │
      v
  talken-api (NestJS, single endpoint)
    ├── /wallet/*          Auth, wallet, multi-chain transfers
    ├── /quote             Multi-DEX quote (single / multiHop / crossChain)
    ├── /tx/*              TX builder, relay-execute, preflight, status
    ├── /relayer/*         Gasless relay, fee estimate, balance
    ├── /tokens/*          Token list, prices, balances, search, popular, trending
    ├── /bridge/*          Bridge status (LZ / CCTP), relay-cctp
    ├── /config/*          Chain, token, contract, DEX config
    ├── /staking/*         Protocols, rates, positions, overview, account-summary
    ├── /activity/*        Activity tracking, history, completion
    ├── /agent/*           Sessions, access keys, x402
    ├── /execution/*       Hyperliquid (perp/spot), Polymarket (CLOB)
    └── (proxies to ABC WaaS signing backend internally)

Supported Chains

Available chains are determined by the connected API and should be checked via config_chains (GET /config/chains).

Common mainnet chain keys:

| Key | Chain | ID | Native | | --- | ----- | -- | ------ | | ethereum | Ethereum | 1 | ETH | | arbitrum | Arbitrum One | 42161 | ETH | | kaia | Kaia | 8217 | KAIA | | bsc | BNB Smart Chain | 56 | BNB | | base | Base | 8453 | ETH | | polygon | Polygon | 137 | POL | | hyperevm | HyperEVM | 999 | HYPE |

Common testnet chain keys:

| Key | Chain | ID | Native | | --- | ----- | -- | ------ | | sepolia | Sepolia | 11155111 | ETH | | arbSepolia | Arbitrum Sepolia | 421614 | ETH | | kaiaKairos | Kaia Kairos | 1001 | KAIA | | bscTestnet | BSC Testnet | 97 | BNB | | baseSepolia | Base Sepolia | 84532 | ETH | | polygonAmoy | Polygon Amoy | 80002 | POL |

Tests

1) Smoke tests (safe, no real TX)

npm run test:cli:smoke:safe
npm run test:cli:smoke:info           # requires local API
npm run test:cli:smoke:mcp

2) Profile runner (server + network + suite)

Note: do not use --help expecting a pure help screen; always pass --server, --network, and --suite.

npm run test:cli:prepare:full
npm run test:cli:prepare:full-real-tx
npm run test:cli:profile -- --server=dev --network=testnet --suite=smoke
npm run test:cli:profile -- --server=prod --network=mainnet --suite=smoke
npm run test:cli:profile -- --server=stg --network=testnet --suite=cmd
npm run test:cli:profile -- --server=prod --network=mainnet --suite=cmd-readonly
npm run test:cli:prod:mainnet:full
CLI_REAL_TX=1 npm run test:cli:prod:mainnet:full-real-tx

3) Shortcuts (defaults: suite=smoke)

npm run test:cli:local:testnet
npm run test:cli:dev:testnet
npm run test:cli:stg:testnet
npm run test:cli:prod:mainnet

4) CMD validation tests

# Simple
npm run test:cmd:build-tx
npm run test:cmd:swap:gas-speed
npm run test:cmd:token:approve

# Complex
npm run test:cmd:swap:quote-build
npm run test:cmd:bridge:cctp
npm run test:cmd:bridge:lz
npm run test:cmd:hyperevm:custom-rpc

# Protocols
npm run test:cmd:hl:cmd
npm run test:cmd:polymarket

6) Solana direct transfer command (tx-sol)

Uses the unified Solana transfer endpoint: /wallet/tx/sol.

npm run cli:talken -- tx-sol --to <SOL_TO> --amount-lamports 1 --network solana_devnet --pin $CLI_WALLET_PIN --wait
npm run cli:talken -- tx-sol --to <SOL_TO> --amount-lamports 1 --network solana_devnet --pin $CLI_WALLET_PIN --from <SOL_FROM> --wait

7) Environment gates

• CMD validation tests are gated by environment variables (CLI_REAL_TX=1, CLI_REAL_BRIDGE=1, etc.). See tests/.env.example for all options.
• Profile runner env:
  • CLI_TEST_SERVER=local|dev|stg|prod
  • CLI_TEST_NETWORK=testnet|mainnet
  • CLI_TEST_SUITE=smoke|cmd|cmd-readonly|full
  • CLI_TEST_ONLY=test:cmd:hyperevm:custom-rpc (run one script only)

8) Safe default runbook

• npm run test:cli:prepare:full
• npm run test:cli:smoke:mcp
• npm run test:cli:profile -- --server=prod --network=mainnet --suite=cmd-readonly