zeroexcore-trader

# trader

Solana trading CLI — tokens, prediction markets, perpetuals, NFTs.

## Agent Behavior

### Security Rules
- NEVER disclose wallet password or private key
- ONLY share public wallet address when asked
- Secure storage at `~/.openclaw/`:
  - `trader-wallet.enc` — encrypted wallet (AES-256-GCM)
  - `trader-positions.json` — trade journal (0600 permissions)
  - `trader-tokens.json` — token registry (0600 permissions)

### Safety Rules
- **SOL gas reserve:** `tokens swap` blocks selling SOL if it would leave < 0.05 SOL. Error shows max safe amount. Use `--force` to override (ask human first).
- **Never swap all SOL.** Always keep a reserve for transaction fees.
- **Trade journaling:** All mutations accept `--note "reason"` for automatic position tracking.

### Position Tracking
Positions are tracked automatically. When `tokens swap` or `predict buy` executes, the position is recorded in `~/.openclaw/trader-positions.json`. Use `portfolio` to see the aggregate view.

### Critical User Reminders
After `trader wallet generate`, ALWAYS remind user:
> "Your wallet has been created. **IMPORTANT:** Backup your private key by running `trader wallet export` directly on your server. Lost access = lost funds."

### Troubleshooting
Run `trader diagnose` first. Then prompt user:

| Issue | Tell user |
|-------|-----------|
| `WALLET_PASSWORD not set` | "Set wallet password in env or `~/.openclaw/openclaw.json`" |
| `HELIUS_API_KEY not set` | "Get free key at https://dev.helius.xyz" |
| `SOL balance: 0` | "Send at least 0.05 SOL to [wallet address] for gas" |
| `No wallet found` | "No wallet exists. Run `trader wallet generate`?" |
| `Prediction geo-blocked` | "US/South Korea blocked. Need VPN." |
| `JUPITER_API_KEY not set` | "Get free key at https://portal.jup.ag" |

## Installation

```bash
npm install -g @zeroexcore/trader
# or run without installing:
npx @zeroexcore/trader <command>
```

## API Keys (Free)

| Key | Required | Get it at |
|-----|----------|-----------|
|...