> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zhentan.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Get Zhentan running locally with full AI screening in minutes.

## Prerequisites

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

You'll also need accounts for:

* [Privy](https://privy.io) — embedded wallets, Google OAuth, and wallet login
* [Safe API key](https://developer.safe.global) — Safe Transaction Service access (proposal mirroring + sync)
* Telegram bot token — for review notifications
* [Zerion](https://zerion.io) — portfolio data (optional)
* [Pimlico](https://pimlico.io) — **legacy accounts only** (pre-refactor 4337 rows and treasury payouts)

<Note>
  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.
</Note>

## Install

This is a pnpm workspace. Run from the root:

```bash theme={null}
pnpm install
```

## Configure Environment

<Tabs>
  <Tab title="Client">
    Create `client/.env.local`:

    ```env theme={null}
    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
    ```
  </Tab>

  <Tab title="Server">
    Create `server/.env`:

    ```env theme={null}
    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
    ```
  </Tab>
</Tabs>

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

## Run Locally

<Steps>
  <Step title="Start the server">
    ```bash theme={null}
    pnpm dev:server
    # → http://localhost:3001
    ```
  </Step>

  <Step title="Start the client">
    ```bash theme={null}
    pnpm dev:client
    # → http://localhost:3000
    ```
  </Step>

  <Step title="Set up the NanoBot/Hermes agent">
    ```bash theme={null}
    # 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
    ```
  </Step>
</Steps>

## Verify It Works

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

## Troubleshooting

<AccordionGroup>
  <Accordion title="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`.
  </Accordion>

  <Accordion title="No Telegram notification">
    Verify `TELEGRAM_BOT_TOKEN` is set in `server/.env` and the bot has been started in your Telegram chat.
  </Accordion>

  <Accordion title="Safe not deploying">
    Confirm BNB Chain RPC is reachable and the agent EOA has enough BNB to pay deployment gas.
  </Accordion>

  <Accordion title="Balance not showing">
    `ZERION_API_KEY` may be missing from `server/.env`. Portfolio data requires a valid Zerion API key.
  </Accordion>
</AccordionGroup>