Billionr

Billionr is a stock analysis system plus an authenticated terminal product. The scheduled Python models fetch market data, calculate RoRo, calls, puts, and squeeze signals, then persist structured outputs for a Next.js API and the billionr CLI.

Product Surface

• Website/API: Next.js app with a public product page and a compact /api/cli/* JSON API.
• CLI: billionr, an npm-distributed command for terminal and AI-agent access.
• Auth: Supabase email/password sessions. Access is free for now but authenticated.
• Data: Historical ticker candles from finnhub, RoRo history from roro, and persisted model recommendations from option_signals.

CLI Commands

npm install -g billionr
billionr config set api-url https://www.billionr.ai

billionr signup            # sends confirmation email
# click the link in your inbox, then:
billionr login
billionr whoami

billionr tickers --search NV
billionr ticker AAPL
billionr history AAPL --days 90
billionr calls --symbol NVDA --latest
billionr puts --symbol TSLA --latest
billionr squeeze --latest
billionr roro --latest

Always use https://www.billionr.ai (the apex billionr.ai redirects, adding a roundtrip to every call). JSON is the canonical output format. Use --table for a compact human-readable table.

Local Setup

1. Install Node dependencies:

npm install

2. Copy environment variables:

cp .env.example .env.local

3. Configure:

• NEXT_PUBLIC_SUPABASE_URL
• NEXT_PUBLIC_SUPABASE_ANON_KEY
• DATABASE_URL or the existing POSTGRESQL_STOCKS_* variables

4. Apply the database schema:

npm run db:schema

5. Run the website/API:

npm run dev

6. Point the CLI at local API:

node ./bin/billionr.mjs config set api-url http://localhost:3000
node ./bin/billionr.mjs signup
node ./bin/billionr.mjs login

Existing Models

• finnhub_data_fetch.py: fetches price data from Finnhub/Yahoo Finance.
• roro_gauge.py: calculates and stores Risk-on/Risk-off gauge values.
• calls_model.py: identifies call-side stock opportunities.
• puts_model.py: identifies put-side stock opportunities.
• squeeze_model.py: detects squeeze setups.

The calls, puts, and squeeze scripts now persist structured signals via signal_persistence.py before sending Slack messages.

GitHub Actions

The workflows still use GitHub secrets for database credentials:

• POSTGRE_STOCKS_HOST
• POSTGRE_STOCKS_PORT
• POSTGRE_STOCKS_DATABASE
• POSTGRE_STOCKS_USER
• POSTGRE_STOCKS_PASSWORD
• OPENAI_API_KEY

Slack webhook URLs must also be GitHub secrets:

• SLACK_WEBHOOK_CALLS_RORO
• SLACK_WEBHOOK_CALLS_STOCKS
• SLACK_WEBHOOK_STATUS
• SLACK_WEBHOOK_PUTS_CONDITIONAL
• SLACK_WEBHOOK_PUTS_ALWAYS
• SLACK_WEBHOOK_SQUEEZE_CONDITIONAL
• SLACK_WEBHOOK_SQUEEZE_ALWAYS
• SLACK_WEBHOOK_RORO

If old Slack webhook URLs were committed before, rotate them in Slack.

Security Notes

• The CLI never stores raw passwords.
• Supabase service-role keys must never be exposed to the browser or CLI.
• The CLI stores session tokens in the OS keychain when available and falls back to an owner-only local file.
• The API validates Supabase sessions before reading ticker or prediction data.
• API inputs are bounded and parameterized.
• Free access is still rate-limited per authenticated user and IP.
• Authenticated API requests are written to api_usage_events for audit and abuse-monitoring readiness.

Python Requirements

The existing scripts install their own Python dependencies at runtime:

• pandas
• numpy
• sqlalchemy
• psycopg2-binary
• requests
• ta
• yfinance
• finnhub-python
• pytz
• lxml
• openai

License

The published billionr npm package (CLI source under bin/) is MIT licensed. See LICENSE. The rest of the repository (Next.js website, Python models, GitHub Actions, database schema) is private and not licensed for redistribution.