# leapcat

Command-line interface for the Leapcat stock trading platform. Supports authentication, KYC, IPO subscription, stock trading, wallet management, portfolio, and market data — all with `--json` output for AI agent integration.

## Requirements

- **Node.js >= 18** (for native `crypto.subtle`, `fetch`, `FormData`)

## Installation

```bash
npm install -g leapcat
```

Or for development:

```bash
cd cli
npm install
npm run build
npm link   # makes `leapcat` available globally
```

Run directly without building:

```bash
npx tsx src/index.ts <command>
```

## Quick Start

```bash
# Check server health
leapcat health check --json

# Login (interactive)
leapcat auth login --email you@example.com

# Login (non-interactive, for agents)
leapcat auth login --email you@example.com --send-only --json
# → { "success": true, "data": { "otp_id": "..." } }
leapcat auth login --email you@example.com --otp-id <id> --otp-code <code> --json

# Check balance
leapcat wallet balance --json

# Get market quote
leapcat market quote --symbol AAPL --json

# Place an order
leapcat trading place-order --symbol AAPL --exchange NASDAQ --side BUY --order-type LIMIT --quantity 10 --price 150 --json
```

## Commands

| Group           | Commands |
|-----------------|----------|
| `auth`          | `login`, `logout`, `status`, `refresh`, `reauth`, `trade-password` |
| `account`       | `me`, `update-profile` |
| `upload`        | (direct) `--file` |
| `kyc`           | `consent`, `documents`, `personal-info`, `supplementary`, `agreements`, `submit`, `status`, `detail` |
| `ipo`           | `projects`, `project`, `estimate`, `subscribe`, `cancel`, `subscriptions`, `subscription` |
| `trading`       | `place-order`, `list-orders`, `cancel-order`, `get-order` |
| `wallet`        | `balance`, `deposit-address`, `deposits`, `deposit`, `withdraw`, `withdrawals`, `debt-status`, `fund-activities` |
| `portfolio`     | `overview`, `positions` |
| `market`        | `quote`, `kline`, `kline-latest`, `stock-detail`, `indices`, `overview`, `stocks` |
| `config`        | `exchange-rate`, `fee-rate`, `withdrawal-fees` |
| `notifications` | `list`, `mark-read`, `preferences`, `update-preferences` |
| `health`        | `check`, `ready` |

## JSON Mode

All commands support `--json` (or `--raw`) for structured output:

```json
{ "success": true, "data": { ... } }
```

On error:

```json
{ "success": false, "error": { "code": "NOT_AUTHENTICATED", "message": "..." } }
```

## Configuration

| File | Purpose |
|------|---------|
| `~/.config/leapcat/tokens.json` | Auth tokens (auto-managed, `chmod 600`) |
| `~/.config/leapcat/.env` | Optional env overrides |

### Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `LEAPCAT_API_URL` | `https://api.leapcat.ai` | Backend API URL |
| `TURNKEY_ORGANIZATION_ID` | (hardcoded) | Turnkey org ID override |
| `TURNKEY_AUTH_PROXY_CONFIG_ID` | (hardcoded) | Turnkey auth proxy config ID override |

## AI Agent Skills

This package includes 7 Cursor skills in `skills/`:

- **leapcat-auth** — Authentication flow
- **leapcat-kyc** — KYC verification
- **leapcat-ipo** — IPO subscription
- **leapcat-trading** — Stock trading
- **leapcat-wallet** — Wallet management
- **leapcat-portfolio** — Portfolio overview
- **leapcat-market** — Market data & config

Skills are defined in `.cursor-plugin/skills.json` for Cursor IDE integration.

## Architecture

```
leapcat
    │
    ├── Turnkey Auth Proxy  (P-256 OTP flow, no SDK needed)
    │       ↓
    └── Leapcat user-gateway  (REST API)
            ↓
        Backend gRPC services
```

## License

MIT