Quickstart

Prerequisites

Tool	Version
Node.js	18+
pnpm	10+
NanoBot/Hermes CLI	latest

You’ll also need accounts for:

Privy — embedded wallets, Google OAuth, and wallet login
Safe API key — Safe Transaction Service access (proposal mirroring + sync)
Telegram bot token — for review notifications
Zerion — portfolio data (optional)
Pimlico — legacy accounts only (pre-refactor 4337 rows and treasury payouts)

The agent EOA relays every execution and deploys Safes — it must hold BNB for gas. The AGENT_MIN_BNB threshold (default 0.05) triggers a low-balance alert.

Install

This is a pnpm workspace. Run from the root:

pnpm install

Configure Environment

Client
Server

Create client/.env.local:

NEXT_PUBLIC_PRIVY_APP_ID=your_privy_app_id
NEXT_PUBLIC_AGENT_ADDRESS=0xYourAgentAddress
NEXT_PUBLIC_BACKEND_URL=http://localhost:3001
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_walletconnect_project_id

Create server/.env:

AGENT_PRIVATE_KEY=0xYourAgentPrivateKey
SAFE_API_KEY=your_safe_transaction_service_key
SAFE_DERIVATION_VERSION=2
AGENT_MIN_BNB=0.05
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
ZERION_API_KEY=your_zerion_api_key
PIMLICO_API_KEY=your_pimlico_api_key   # legacy 4337 rows + treasury only
PORT=3001
QUEUE_PATH=./pending-queue.json

See scripts/.env.example and server/.env.example for full templates.

Run Locally

Start the server

pnpm dev:server
# → http://localhost:3001

Start the client

pnpm dev:client
# → http://localhost:3000

Set up the NanoBot/Hermes agent

# Symlink the skills into NanoBot/Hermes's workspace
mkdir -p ~/.nanobot/workspace/skills
ln -sf "$(pwd)/agent" ~/.nanobot/workspace/skills/zhentan

# Restart the gateway
nanobot gateway restart

# Verify detection
nanobot skills check

Verify It Works

Visit http://localhost:3000
Sign in with Google (embedded wallet) or connect a wallet — then pick a profile during onboarding
A Safe multisig is deployed on BNB Chain (the agent pays gas)
Navigate to Send → enter a recipient and amount
Confirm → the SafeTx is queued and visible at app.safe.global at 1/2
Check server logs for the risk score and verdict
APPROVE: the agent confirms and relays — txHash appears in the UI
REVIEW: check Telegram for the interactive approve/reject message (or override with your backup key in the Safe app)

Troubleshooting

Transaction stuck in queue

Verify AGENT_PRIVATE_KEY is set and the agent EOA holds BNB — it relays every execution. If the proposal isn’t visible in app.safe.global, check SAFE_API_KEY.

No Telegram notification

Verify TELEGRAM_BOT_TOKEN is set in server/.env and the bot has been started in your Telegram chat.

Safe not deploying

Confirm BNB Chain RPC is reachable and the agent EOA has enough BNB to pay deployment gas.

Balance not showing

ZERION_API_KEY may be missing from server/.env. Portfolio data requires a valid Zerion API key.

Get Started

Zhentan App

Technology

Prerequisites

Install

Configure Environment

Run Locally

Verify It Works

Troubleshooting

​Prerequisites

​Install

​Configure Environment

​Run Locally

​Verify It Works

​Troubleshooting

Prerequisites

Install

Configure Environment

Run Locally

Verify It Works

Troubleshooting