Somnia Agent Kit

All-in-one MCP toolkit for the Somnia blockchain, in TypeScript.

Wallet operations · local-only signing · transfers · contract deploy · staking (delegate / undelegate / claim) · full chain exploration — from Claude Code, Cursor, Codex, or directly via the Vercel AI SDK.

Built for humans. Perfect for AI.

Why Somnia Agent Kit

Your private key never leaves your machine. MCP only prepares unsigned transactions — signing happens locally, and the key is never sent to the AI model or a remote server.

Two protection levels.

Simple — a guard hook blocks the agent from reading .env.
Secure — encrypted keystore + a signing daemon in a separate, isolated process; the agent only ever receives the signed hex.

Two ways to use.

Subscription (free) — connect MCP to Claude Code / Cursor / Codex and use your existing subscription.
AI SDK (developers) — programmatic agents via the Vercel AI SDK with Claude or OpenAI.

Somnia-native. Beyond plain EVM: delegate SOMI to validators (prepare_delegate), undelegate, claim delegator rewards, read your delegations, and explore the full chain (blocks, txs, accounts, contracts, tokens, validators).

⚠️ Mainnet — real funds. The default network is Somnia mainnet (chainId 5031, native SOMI). /send, /deploy, and /stake move real SOMI. There is no faucet on mainnet — fund your address from an exchange/bridge, or point the kit at a Somnia testnet MCP deployment (token STT) for low-risk demos. Prefer secure mode with manual approval (npm run signer -- --manual) so every signature needs your y/n.

Architecture

┌────────────────────────────┐
│  You (chat or code)        │
├────────────────────────────┤
│  AI Agent                  │
│  (Claude / GPT / local)    │
│                            │
│  Sees: wallet address,     │
│        MCP tool results    │
│  Never sees: private key   │
├──────────┬─────────────────┤
│ sign-tx  │  MCP Server     │
│ (local)  │  (remote)       │
│          │                 │
│ Signs tx │  prepare_*      │
│ locally  │  broadcast/wait │
│          │  query blocks   │
│ Key in   │  stake          │
│ .env or  │  read contract  │
│ keystore │  explorer       │
└──────────┴─────────────────┘

Key principle: the private key NEVER leaves your machine. MCP prepares the unsigned tx → you sign locally → the signed tx is broadcast back through MCP.

ℹ️ Somnia's prepare_* tools return an unsigned tx without a gas limit; the local signer estimates gas against SOMNIA_RPC_URL (a read-only call) before signing, then — in secure mode — hands the fully-formed tx to the network-isolated daemon.

Quick Start — Claude Code (subscription)

# Clone
git clone https://github.com/stakeme-team/somnia-agent-kit
cd somnia-agent-kit

# Install (in Docker for supply-chain safety)
docker run --rm --network host -v "$(pwd):/app" -w /app node:20-alpine npm install

# Create a wallet
npx tsx scripts/wallet-manager.ts generate --simple

# Open Claude Code
claude

Claude Code auto-detects .mcp.json and connects to the Somnia MCP server. Then just chat:

"Send 0.001 SOMI to a random address from a recent transaction"

See also: Cursor setup · Codex setup · ready-made prompts

Quick Start — AI SDK (programmatic)

git clone https://github.com/stakeme-team/somnia-agent-kit
cd somnia-agent-kit
docker run --rm --network host -v "$(pwd):/app" -w /app node:20-alpine npm install

cp .env.example .env
npx tsx scripts/wallet-manager.ts generate --simple
# Edit .env: add ANTHROPIC_API_KEY or OPENAI_API_KEY

npm run demo:wallet    # show wallet address & SOMI balance
npm run demo:send      # send SOMI to a random recent address
npm run demo:stake     # delegate SOMI to a validator

Switch model provider in .env:

AI_PROVIDER=anthropic   # or openai

Skills

Built-in Claude Code / Cursor skills (slash commands):

Skill	What it does
`/wallet`	Show wallet address & native SOMI balance
`/send`	Send SOMI to an address (or a random recent one)
`/deploy`	Deploy a smart contract and read it back
`/stake`	Delegate/undelegate SOMI, claim rewards, review validators (see Staking)

Security

Simple mode (default)

Private key in .env, protected by a guard hook that blocks the agent from reading it.

npx tsx scripts/wallet-manager.ts generate --simple
npm run security-test
# ✓ cat .env            → BLOCKED
# ✓ grep PRIVATE .env   → BLOCKED
# ✓ echo $PRIVATE_KEY   → BLOCKED
# ✓ python3 read .env   → BLOCKED
# ... all passed ✓

Secure mode (signing daemon)

Private key encrypted in a keystore, decrypted only inside a separate daemon process. The agent physically cannot reach the key.

# Create an encrypted wallet
npx tsx scripts/wallet-manager.ts generate --secure

# Start the daemon (separate terminal)
npx tsx scripts/signer-daemon.ts            # auto-approve
npx tsx scripts/signer-daemon.ts --manual   # ask y/n per transaction

┌───────────────────┐     ┌───────────────────┐
│  Agent            │     │  Signer Daemon     │
│  (no key access)  │────▶│  (key in memory)   │
│                   │unix │                    │
│  Gets: signed hex │◀────│  Signs tx          │
└───────────────────┘sock └───────────────────┘

In --manual mode every signing request prints the tx details and waits for your y/n — ideal on mainnet. Gas is estimated by the caller before the request, so the daemon stays network-isolated.

Docker isolation

docker compose run --rm install                  # install deps in a container
docker compose run --rm dev npx tsx examples/02-send-tokens.ts
docker compose up signer                          # signer daemon, NO network access

Staking

Somnia delegation goes through a single staking contract (0xBe367d410D96E1cAeF68C0632251072CDf1b8250); the MCP encodes the call for you. Pass validator = the validator's address from list_validators (0x-prefixed) and from = your wallet.

prepare_delegate (from, validator, amountWei) — payable: the tx value carries the stake → delegateStake(validator, amount).
prepare_undelegate (from, validator, amountWei) → undelegateStake(validator, amount).
prepare_claim_rewards (from, validator) → claimDelegatorRewards(validator).
Read: get_delegations (validators you delegate to), get_delegation_info (amount + pendingRewards), list_validators, get_validator_by_address.

Amounts are in wei (SOMI × 10¹⁸). parseEther("1.5").toString() → "1500000000000000000".

⚠️ Mainnet — real funds. /stake spends real SOMI; confirm the amount and prefer secure mode (y/n per signature). For a dry run, point the kit at a Somnia testnet deployment first.

MCP Tools

The Somnia MCP server at https://api.somnia.exploreme.pro/mcp exposes the explorer's read tools plus the write tools below:

Category	Tools
Transactions (write)	`prepare_native_transfer`, `prepare_transaction`, `broadcast_signed_raw_transaction`, `wait_for_transaction`
Staking (write)	`prepare_delegate`, `prepare_undelegate`, `prepare_claim_rewards`
Staking (read)	`get_delegations`, `get_delegation_info`, `list_validators`, `get_validator_by_address`, `get_validator_delegators`, `get_validators_statistics`, `get_evm_top_delegators`, `get_account_delegations`
Balances / contract reads	`rpc_native_balance`, `rpc_token_balance`, `rpc_read_contract`
Accounts	`get_evm_account_by_address`, `get_account_transactions`, `get_account_tokens`, `get_account_token_transfers`, `get_account_total_gas`, `get_evm_top_accounts`
Blocks / txs	`list_evm_blocks`, `get_evm_block_by_height`, `list_evm_transactions`, `list_evm_transactions_by_block`, `get_evm_transaction_by_hash`, `get_evm_transaction_logs`, `get_evm_transaction_state`
Contracts	`list_evm_contracts`, `get_evm_contract_by_address`, `get_evm_contract_code`, `get_evm_compiler_versions`
Tokens	`get_token_by_contract_address`
Chain / search	`get_chain_network`, `get_evm_indexer_info`, `get_evm_gas_tracker`, `explorer_search`

There is no faucet or on-chain contract-verification tool on Somnia mainnet — verify source via the explorer UI: https://somnia.exploreme.pro/contracts/verify.

Project Structure

somnia-agent-kit/
├── CLAUDE.md                    # Agent instructions for Somnia
├── .mcp.json                    # Claude Code MCP config
├── .cursor/mcp.json             # Cursor MCP config
├── .codex/config.toml           # Codex MCP config (via mcp-remote)
│
├── .claude/
│   ├── settings.json            # Guard hook config
│   └── skills/                  # /wallet · /send · /deploy · /stake
│
├── scripts/
│   ├── wallet-manager.ts        # Create / import wallet
│   ├── sign-tx.ts               # Sign tx (stdin → stdout), estimates gas
│   ├── signer-daemon.ts         # Signing daemon (secure mode)
│   ├── guard.sh                 # Block agent from reading keys
│   ├── security-test.ts         # Test guard (attack vectors)
│   └── run-stake-flow.ts        # Scripted delegate flow
│
├── src/                         # AI SDK core library
│   ├── mcp-client.ts            # MCP client factory
│   ├── wallet.ts                # Wallet (address only for the LLM)
│   ├── signing-bridge.ts        # Auto-sign prepare_* results
│   ├── tx.ts                    # Unwrap envelope + estimate gas + normalize
│   ├── result.ts                # Parse MCP tool results
│   ├── agent.ts                 # Agent factory (Claude + OpenAI)
│   └── utils.ts                 # Helpers
│
├── examples/                    # AI SDK demos (wallet · send · stake)
├── contracts/                   # SimpleStorage.sol (+ compiled)
├── docs/                        # setup guides + prompts
├── Dockerfile
└── docker-compose.yml

Requirements

Node.js 20+ and npm
Docker — optional, recommended for supply-chain-isolated installs and the network-less signer
Subscription path: Claude Pro/Max, Cursor Pro, or ChatGPT Pro
AI SDK path: an Anthropic or OpenAI API key

Configuration

Env var	Default	Purpose
`SOMNIA_MCP_URL`	`https://api.somnia.exploreme.pro/mcp`	MCP server (read + write tools)
`SOMNIA_RPC_URL`	`https://somnia-rpc.stakeme.pro`	Node RPC used by the local signer to estimate gas
`SIGNER_MODE`	`simple`	`simple` (key in .env) or `secure` (keystore + daemon)

To target a Somnia testnet deployment, set SOMNIA_MCP_URL (and SOMNIA_RPC_URL) to the testnet endpoints in .env.

License

MIT

Navigation Menu

Repository navigation

About

Repository files navigation

Somnia Agent Kit

Why Somnia Agent Kit

Architecture

Quick Start — Claude Code (subscription)

Quick Start — AI SDK (programmatic)

Skills

Security

Simple mode (default)

Secure mode (signing daemon)

Docker isolation

Staking

MCP Tools

Project Structure

Requirements

Configuration

License

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
.claude		.claude
.codex		.codex
.cursor		.cursor
assets		assets
contracts		contracts
docs		docs
examples		examples
scripts		scripts
src		src
.env.example		.env.example
.gitignore		.gitignore
.mcp.json		.mcp.json
CLAUDE.md		CLAUDE.md
Dockerfile		Dockerfile
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation

Somnia Agent Kit

Why Somnia Agent Kit

Architecture

Quick Start — Claude Code (subscription)

Quick Start — AI SDK (programmatic)

Skills

Security

Simple mode (default)

Secure mode (signing daemon)

Docker isolation

Staking

MCP Tools

Project Structure

Requirements

Configuration

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages