# Zoi Agent

Zoi Agent is being built as two independent products:

- A public website that displays real, verifiable Agent and Pons activity.
- A self-hosted Agent that runs on the user's VPS with the user's APIs, wallet, and capital.

The public website never stores wallet private keys and never executes trades for visitors. A separate, authenticated `/operator` control plane can provision one execution wallet into the Agent's encrypted vault and enqueue launches or fee claims. Completed financial actions must resolve to public Robinhood Chain transaction hashes.

## Current milestone

The Agent is the primary product. It currently provides mainnet configuration checks, xAPI trend collection, validated 5.6sol decisions, Pons launch simulation/execution, automatic creator-fee claims, a balanced 50/50 allocation ledger, and guarded WETH buybacks. Non-WETH fee allocations are converted through their verified Pons WETH pool before the hotspot buyback, with the same slippage, price-impact, reservation, and receipt-recovery controls. The website reads public chain data and signed Agent events; it does not expose installation controls.

```text
Network: Robinhood Chain
Chain ID: 4663
Pons factory: 0xA5aAb3F0c6EeadF30Ef1D3Eb997108E976351feB
```

## Local development

```bash
npm install
npm run dev
```

Open `http://127.0.0.1:3000`.

Optional configuration:

```bash
ROBINHOOD_RPC_URL=https://rpc.mainnet.chain.robinhood.com
ROBINHOOD_RPC_URLS=https://rpc-backup.example,https://rpc-second.example
XAPI_BASE_URL=https://action.xapi.to
```

## Verification

```bash
npm run lint
npm run build
```

## Agent commands

```bash
npm run cli --workspace @pons-agent/runtime -- doctor
npm run cli --workspace @pons-agent/runtime -- scan-once
npm run cli --workspace @pons-agent/runtime -- launch --file examples/token.json --initial-buy 0
npm run cli --workspace @pons-agent/runtime -- claim-once
npm run cli --workspace @pons-agent/runtime -- buyback --token 0x... --amount 0.01
npm run cli --workspace @pons-agent/runtime -- reconcile
npm run cli --workspace @pons-agent/runtime -- status
npm run cli --workspace @pons-agent/runtime -- run
```

The Agent can also run as an isolated VPS service using `docker-compose.agent.yml`. Runtime secrets belong in `apps/agent/.env`; that file is ignored by Git and is never read by the public website. xAPI uses the `twitter.search` action through `https://action.xapi.to/v1/actions/execute` with the `XAPI-Key` header; the Agent aggregates real tweet hashtags and engagement into candidates before sending them to the model.

Automatic launches do not use a fixed logo. Configure `TOKEN_ASSET_ENDPOINT` and `TOKEN_ASSET_PUBLIC_BASE_URL`; the Agent derives a deterministic logo from the approved token identity, signs it with the execution wallet, publishes it to the website, and verifies the immutable public SVG before simulating or sending a Pons launch.

The container runs as a non-root user with a read-only root filesystem. SQLite state, cycle history, the allocation ledger, and the signed-event outbox are stored in the `pons-agent-state` volume. Configure the public website with the Agent wallet address in `PUBLIC_AGENT_WALLETS`; never place `EVM_PRIVATE_KEY` in the website environment.

## Private operator control

Create the internal Docker network once with `docker network create pons-control`, then enable `CONTROL_ENABLED` in the Agent environment. `CONTROL_PASSWORD`, `CONTROL_INTERNAL_TOKEN`, and `WALLET_MASTER_KEY` are server-only secrets. The web service receives only the matching internal token and proxies `/api/operator/*` over the private Docker network; the browser never receives that token.

The wallet private key is submitted once over HTTPS, encrypted with AES-256-GCM inside the Agent process, and stored in the Agent volume. The private key is never returned by an API. Connecting a browser wallet only verifies that the imported signing key resolves to the intended address. Operator launch and claim commands are durably queued and run under the Agent's existing wallet execution lease.

## Recovery behavior

Every live launch, fee claim, and buyback is recorded locally before its signed transaction is broadcast. On restart, `run` and `reconcile` query Robinhood Chain receipts and rebuild the launch registry, fee allocation ledger, or buyback result. A reverted buyback releases its reservation; a successful or still-uncertain transaction keeps the reservation frozen until its outcome is known. Executions with no recorded transaction hash are never auto-released and require operator review.

The public event outbox is durable. If the website is unavailable, signed events remain pending and are retried later; a confirmed execution whose event was interrupted is published from the execution ledger on the next cycle. The website only accepts events signed by configured Agent wallets and verifies transaction-bearing events against Robinhood Chain.

## Live-mode checklist

Use `AGENT_MODE=observe` first. Run `doctor`, `scan-once`, and the simulation paths with a dedicated state database and RPC failover. Only enable `AGENT_MODE=live` after setting `LIVE_TRADING_ACK=I_ACCEPT_REAL_MONEY_EXECUTION`, funding the execution wallet with a limited operating balance, and confirming `MAX_LAUNCH_TOTAL_ETH`, `MIN_GAS_RESERVE_ETH`, `MAX_SLIPPAGE_BPS`, `MAX_PRICE_IMPACT_BPS`, and `BUYBACK_CHUNK_BPS`.

Keep `apps/agent/.env` on the VPS only. The private key, XAPI key, and model key are runtime secrets; they are not copied into the web app, public event payloads, Docker image, or repository.
