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

Install

Global npm

npm i -g @paranoid-bull/bull

One-off run with npx

npx @paranoid-bull/bull run

Build from source

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:

cp .env.example .env

2. Initialize config and secrets:

bull init

3. Run doctor checks:

bull doctor

4. Start TUI:

bull run

If you plan to use the embedded bridge adapter, install Chromium once:

npx playwright install chromium

Demo Screens

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:

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):

BULL_ADAPTER_ORDER=external_multiplexer,embedded_bridge
AXIOM_BRIDGE_PROFILE_DIR=~/.bull/axiom-profile
AXIOM_BRIDGE_HEADLESS=0

Environment

Minimum useful setup:

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.

Optional market fallback:

• BULL_DEFAULT_SOL_PRICE_USD=90 sets the initial SOL/USD conversion until live sol_price_update events arrive.

Architecture

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

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

Release Notes

See RELEASES.md for changelog format.