Stonktop

A top-like terminal UI for monitoring stock and cryptocurrency prices in real-time.

Features

• Real-time Price Monitoring: Live quotes for stocks and cryptocurrencies
• Top-like Interface: Familiar keyboard controls similar to top/htop
• Portfolio Tracking: Monitor your holdings with P/L calculations
• Multiple Sort Options: Sort by symbol, price, change, volume, market cap
• Batch Mode: Non-interactive output for scripting (like top -b)
• TOML Configuration: Easy-to-edit config files
• Color Coded: Green for gains, red for losses
• Crypto Shortcuts: Use BTC.X or just BTC for BTC-USD

Screenshots

STONKTOP - 8 symbols
3 up  4 down  1 unchanged  Updated: 5s ago

SYMBOL     NAME                  PRICE       CHANGE     CHG%        VOLUME      MKT CAP
NVDA       NVIDIA Corporation    $875.28     +12.45     +1.44%      45.2M       $2.16T
AAPL       Apple Inc.            $178.72     +2.31      +1.31%      52.1M       $2.78T
BTC-USD    Bitcoin USD           $43521.00   +521.00    +1.21%      28.5B       $852.1B
GOOGL      Alphabet Inc.         $141.80     +0.95      +0.67%      18.3M       $1.76T
MSFT       Microsoft Corporation $378.91     -1.23      -0.32%      22.4M       $2.81T
ETH-USD    Ethereum USD          $2245.50    -45.20     -1.97%      12.1B       $270.1B
AMZN       Amazon.com Inc.       $178.25     -3.42      -1.88%      31.2M       $1.85T
TSLA       Tesla Inc.            $248.50     -8.75      -3.40%      98.5M       $790.2B

 q:quit h:help s:sort r:reverse H:holdings f:fundamentals | Quotes | CHG% ▼ | Iter: 1

Installation

From crates.io (Recommended)

cargo install stonktop

Using cargo-binstall

If you have cargo-binstall installed, you can install pre-built binaries:

cargo binstall stonktop

Pre-built Binaries

Download pre-built binaries from the Releases page.

Available platforms:

• Linux (x86_64, aarch64, musl)
• macOS (Intel, Apple Silicon)
• Windows (x86_64, aarch64)

From Source

git clone https://github.com/thomasvincent/stonktop.git
cd stonktop
cargo build --release

The binary will be at target/release/stonktop.

For Development

git clone https://github.com/thomasvincent/stonktop.git
cd stonktop
cargo install --path .

Usage

Basic Usage

# Watch specific symbols
stonktop -s AAPL,GOOGL,MSFT,BTC-USD

# With crypto shortcuts
stonktop -s AAPL,BTC,ETH,SOL

Top-like Options

# Set refresh delay (like top -d)
stonktop -s AAPL,GOOGL -d 10

# Run N iterations then exit (like top -n)
stonktop -s AAPL -n 5

# Batch mode for scripting (like top -b)
stonktop -s AAPL,GOOGL -b

# Secure mode - disable interactive commands
stonktop -s AAPL -S

Sorting Options

# Sort by price (descending)
stonktop -s AAPL,GOOGL -o price

# Sort by symbol (ascending)
stonktop -s AAPL,GOOGL -o symbol -r

# Available sort fields: symbol, name, price, change, change-percent, volume, market-cap

Configuration File

# Use specific config file
stonktop -c ~/.config/stonktop/custom.toml

# Or place config at default location:
# - Linux/macOS: ~/.config/stonktop/config.toml
# - Windows: %APPDATA%\stonktop\config.toml

Command Line Options

Keyboard Shortcuts

Configuration

Create a TOML configuration file:

# ~/.config/stonktop/config.toml

[general]
refresh_interval = 5.0
timeout = 10
currency = "USD"

[watchlist]
symbols = [
    "AAPL",
    "GOOGL",
    "MSFT",
    "AMZN",
    "NVDA",
    "BTC-USD",
    "ETH-USD",
]

# Portfolio holdings (optional)
[[holdings]]
symbol = "AAPL"
quantity = 100
cost_basis = 150.00

[[holdings]]
symbol = "BTC-USD"
quantity = 0.5
cost_basis = 30000.00

[display]
show_header = true
show_fundamentals = false
show_holdings = false
sort_by = "change_percent"
sort_descending = true

[colors]
gain = "#00ff00"
loss = "#ff0000"
neutral = "#ffffff"
header = "#1e90ff"
border = "#444444"

# Symbol groups
[groups]
tech = ["AAPL", "GOOGL", "MSFT", "NVDA"]
crypto = ["BTC-USD", "ETH-USD", "SOL-USD"]

Symbol Formats

Data Source

Stonktop uses the Yahoo Finance API to fetch real-time quotes. No API key is required.

Building

Requirements

• Rust 1.70 or later
• Cargo

Development Build

cargo build

Release Build

cargo build --release

Running Tests

cargo test

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Inspired by ticker
• Built with ratatui
• Data from Yahoo Finance