npm package: @paranoid-bull/bull
Description: BULL - terminal-native AI trading companion for real-time memecoin flow, research, and execution.
Author: ParanoidBull
Latest version: 0.1.0

# BULL

<p align="center">
  <img src="docs/assets/banner.jpg" alt="BULL" width="100%" />
</p>

[![npm version](https://img.shields.io/npm/v/@paranoid-bull/bull.svg)](https://www.npmjs.com/package/@paranoid-bull/bull)
[![CI](https://github.com/paranoidbull/bull/actions/workflows/ci.yml/badge.svg)](https://github.com/paranoidbull/bull/actions/workflows/ci.yml)
[![License](https://img.shields.io/github/license/paranoidbull/bull)](./LICENSE)
[![Node](https://img.shields.io/node/v/@paranoid-bull/bull)](https://nodejs.org)
[![npm downloads](https://img.shields.io/npm/dm/@paranoid-bull/bull.svg)](https://www.npmjs.com/package/@paranoid-bull/bull)

BULL is a terminal-native AI trading companion for Solana traders.

It combines:
- Real-time Memescope stream ingestion (multiplexer + Axiom adapters)
- AI-assisted due diligence (OpenRouter + TwitterAPI + Tavily/Exa)
- Signal scoring and ranking
- Manual, guarded-autopilot, and full-autopilot modes
- CLI + TUI experience designed for always-on background operation

## Star History
[![Star History Chart](https://api.star-history.com/svg?repos=paranoidbull/bull&type=Date)](https://star-history.com/#paranoidbull/bull&Date)

## Install

### Global npm
```bash
npm i -g @paranoid-bull/bull
```

### One-off run with npx
```bash
npx @paranoid-bull/bull run
```

### Build from source
```bash
git clone https://github.com/paranoidbull/bull.git
cd bull
npm install
npm run build
node dist/cli.js --help
```

## Quickstart
1. Copy env template:
```bash
cp .env.example .env
```
2. Initialize config and secrets:
```bash
bull init
```
3. Run doctor checks:
```bash
bull doctor
```
4. Start TUI:
```bash
bull run
```

If you plan to use the embedded bridge adapter, install Chromium once:
```bash
npx playwright install chromium
```

## Demo Screens

<p align="center">
  <img src="docs/assets/tui_ss.png" alt="BULL TUI" width="100%" />
</p>

## Modes

| Mode | Behavior |
|---|---|
| `manual` | Suggestions and quotes only. No autonomous execution. |
| `guarded` | Autonomous execution enabled with strict spend/loss/cooldown/open-position limits. |
| `full` | Autonomous execution enabled with looser limits; hard crash guards still enforced. |

Guarded defaults:
- Max `0.2 SOL` per trade
- Max `1.0 SOL` per day
- Max `3` consecutive losses
- Max `5` open positions
- `60s` cooldown between autonomous executions

## Commands

| Command | Purpose |
|---|---|
| `bull init` | Interactive setup and secret capture |
| `bull run` | Launch full TUI runtime |
| `bull chat` | Chat-only mode |
| `bull signals` | Print ranked signals |
| `bull research <entity>` | Run due diligence report |
| `bull trade quote --side --mint --amount` | Create quote |
| `bull trade execute --quote <id>` | Execute quote |
| `bull daemon start` | Start daemon in background |
| `bull daemon stop` | Stop daemon |
| `bull daemon status` | Daemon health and state |
| `bull doctor` | Environment and adapter checks |

## TUI Keybindings
- `Tab`: cycle panes
- `/`: command palette
- `c`: Chat pane
- `s`: Signals pane
- `r`: Research pane
- `t`: Trades pane
- `a`: cycle mode (`manual -> guarded -> full`) with confirmation
- `q`: quit

Panes:
- Market
- Signals
- Research
- Chat
- Trades
- System

## Adapter Strategy
Default startup order (no Axiom credentials required):
1. `external_multiplexer`

Optional full fallback order (Axiom credentials required):
1. `external_multiplexer`
2. `embedded_bridge`
3. `direct_axiom`

### External multiplexer
Uses websocket events and HTTP endpoints from a running multiplexer service.

### Embedded bridge
Spawns Playwright internally and listens to Axiom websocket frames in-browser.
It supports three auth modes:
- Persistent profile mode (default if no Axiom tokens/CDP URL are set): stores a local browser profile for reused login sessions.
- Token inject mode: uses `AUTH_ACCESS_TOKEN` + `AUTH_REFRESH_TOKEN`.
- CDP attach mode: uses `AXIOM_CDP_URL` to attach to an already-debuggable local browser.

### Direct Axiom
Connects directly to Axiom pulse/cluster websockets with session credentials.

To enable optional Axiom adapters:
```env
BULL_ADAPTER_ORDER=external_multiplexer,embedded_bridge,direct_axiom
AUTH_ACCESS_TOKEN=...
AUTH_REFRESH_TOKEN=...
```

To run embedded bridge without token input (persistent profile mode):
```env
BULL_ADAPTER_ORDER=external_multiplexer,embedded_bridge
AXIOM_BRIDGE_PROFILE_DIR=~/.bull/axiom-profile
AXIOM_BRIDGE_HEADLESS=0
```

## Environment
Minimum useful setup:

```env
OPENROUTER_API_KEY=
TWITTER_API_KEY=
HELIUS_API_KEY=
SOLANA_PRIVATE_KEY=
SOLANA_PUBLIC_KEY=
BULL_VAULT_PASSPHRASE=
BULL_MULTIPLEXER_URL=ws://localhost:8080
```

Full template: see [.env.example](./.env.example).

Optional market fallback:
- `BULL_DEFAULT_SOL_PRICE_USD=90` sets the initial SOL/USD conversion until live `sol_price_update` events arrive.

## Architecture

```mermaid
flowchart LR
  A[CLI and TUI] --> B[Runtime]
  B --> C[Adapter Manager]
  C --> D[External Multiplexer]
  C --> E[Embedded Bridge]
  C --> F[Direct Axiom]
  B --> G[Signal Engine]
  B --> H[Research Engine]
  B --> I[Chat Agent]
  B --> J[Execution Engine]
  J --> K[PumpPortal]
  B --> L[SQLite State]
```

## Testing and Quality
```bash
npm run typecheck
npm run build
npm test
```

Test buckets:
- `test/unit`
- `test/integration`
- `test/e2e`

## Security and Safety
- Secrets are stored in keytar when available, otherwise encrypted local vault fallback.
- If keytar is unavailable, set `BULL_VAULT_PASSPHRASE` before storing a private key.
- Private keys are never printed to terminal logs.
- Quote execution is single-use to reduce replay risk.
- Manual mode blocks autonomous execution.
- Guarded/full modes still enforce risk and simulation gates.

Read [SECURITY.md](./SECURITY.md) for reporting and policy details.

## Responsible Use Disclaimer
BULL is not investment advice. Autonomous or manual execution can lose funds. You are responsible for:
- Strategy selection
- Risk settings
- Wallet/key management
- Regulatory and tax compliance

Always test with small size first.

## Contributing
See [CONTRIBUTING.md](./CONTRIBUTING.md).

## Release Notes
See [RELEASES.md](./RELEASES.md) for changelog format.