Quickstart

Prerequisites

Tool	Version
Node.js	18+
pnpm	10+
Supabase CLI	latest
NanoBot/Hermes CLI	latest (optional — only for the conversational agent)

You’ll also need accounts for:

Supabase — the server’s database
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 — treasury payouts only

The sponsor 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
Runtime

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 (see server/.env.example for the full annotated template):

SUPABASE_URL=https://your-project-ref.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your_service_role_key
AGENT_SECRET=shared_secret_for_agent_auth   # or DEV_OPEN=1 for local work
AGENT_ADDRESS=0xYourAgentAddress            # identity only — the KEY lives in runtime/.env
SPONSOR_PRIVATE_KEY=0xYourSponsorKey        # gas-paying EOA
SAFE_API_KEY=your_safe_transaction_service_key
SAFE_DERIVATION_VERSION=2
RUNTIME_API_TOKEN=shared_runtime_bearer     # must match runtime/.env
PRIVY_APP_ID=your_privy_app_id
PRIVY_JWT_VERIFICATION_KEY=your_privy_jwt_key
TELEGRAM_BOT_TOKEN=your_telegram_bot_token
ZERION_API_KEY=your_zerion_api_key
PORT=3001

Then apply the schema: cd server && pnpm db:link && pnpm db:push.

Create runtime/.env (see runtime/.env.example):

RUNTIME_API_URL=http://localhost:3001
RUNTIME_API_TOKEN=shared_runtime_bearer     # must match server/.env
AGENT_PRIVATE_KEY=0xYourAgentPrivateKey     # the ONLY place this key lives
RUNTIME_RPC_URL=https://1rpc.io/bnb

Run Locally

Start the server

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

Start the runtime

pnpm dev:runtime
# pull-only screening/signing worker; health on 127.0.0.1:3002

Without the runtime, every screened proposal stays at screening: "pending" — screening fails closed.

Start the client

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

Set up the NanoBot/Hermes agent (optional)

# Symlink the skill pack 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

The skill talks to the backend through the Zhentan MCP server — see mcp/README.md.

Verify It Works

Visit http://localhost:3000
Sign in with Google (embedded wallet) or connect a wallet — then pick a profile during onboarding
Connect Telegram in one step: say hi to the Zhentan bot, then tap the personal secure link it replies with (the app session confirms the binding)
A Safe multisig is deployed on BNB Chain (the sponsor EOA 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 runtime logs for the risk score and verdict
APPROVE: the runtime signs, the sponsor 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 at screening: pending

The runtime isn’t running or can’t reach the server. Start it with pnpm dev:runtime and verify RUNTIME_API_TOKEN matches between server/.env and runtime/.env — screening fails closed without it.

Transaction screened but not executing

Verify the sponsor EOA (SPONSOR_PRIVATE_KEY) 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 that your Telegram is linked — message the bot and it will reply with a secure link if it isn’t.

Safe not deploying

Confirm BNB Chain RPC is reachable and the sponsor 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