bits

The crypto Swiss Army knife for your terminal.

One CLI, multiple exchanges. Every format. Real-time streams, snapshots, order books, candles — all from the same command set.

⚠️ Library Status: Work in Progress

The public API may change rapidly. Semantic versioning is not yet applied. Use at your own risk. The CLI interface is stable; the library API is not.

What it does

bits price bitcoin ethereum                    # prices from CoinGecko
bits price BTCUSDT -p binance -m futures       # or Binance futures
bits ticker BTCUSDT ETHUSDT -p binance         # 24h stats, parallel fan-out
bits book BTCUSDT -p binance --depth 50        # order book snapshot
bits candles BTCUSDT -p bitget --interval 1h   # OHLCV history
bits stream price bitcoin -o json | jq .price  # live WebSocket → jq
bits capabilities                              # what can each provider do?

Pick a provider with -p, a market with -m, an output format with -o. That's it.

Providers

Provider	Markets	What it gives you
CoinGecko	—	Prices, candles, ranked markets, live price stream
Binance	spot · futures	Server time, exchange info, prices, candles, ticker, order book, live book stream
Bitget	spot · futures	Server time, exchange info, prices, candles, ticker
WhiteBit	spot · futures	Server time, exchange info, prices, candles, ticker, price stream, order book stream
Crypto.com	spot	Prices, ticker, price stream, order book stream
MEXC	spot	Prices, ticker, price stream, order book stream

Switch providers with -p coingecko / -p binance / -p bitget / -p whitebit / -p cryptocom / -p mexc.

Fallback is controlled by whether you use -p:

No -p → fallback allowed; bits auto-routes to a capable provider.
With -p → no fallback by default; bits errors if that provider can't serve the request.
-p ... -f → opt-in to fallback even when the provider is explicit.

bits ticker BTCUSDT                     # no -p → auto-routes to binance
bits ticker BTCUSDT -p coingecko        # error: coingecko does not support ticker
bits ticker BTCUSDT -p coingecko -f     # -f → falls back to binance

Output formats

Every command supports -o with five formats:

Flag	Output
`table`	Aligned tabwriter — human-readable (default)
`json`	Pretty-printed JSON envelope with provenance metadata
`yaml`	Same as JSON but YAML
`markdown`	Markdown doc — heading + fenced YAML block
`toon`	Token friendly structured format

Streaming commands (bits stream) emit continuous compact output per update:

Flag	Streaming output
`json`	JSONL — one compact JSON object per line
`yaml`	One YAML doc per update, `---` separated
`markdown`	One markdown bullet per update
`toon`	Colored inline line per update

Install

# Homebrew
brew install mdnmdn/bits/bits

# Shell script
curl -sSfL https://raw.githubusercontent.com/mdnmdn/bits/main/install.sh | sh

# Go
go install github.com/mdnmdn/bits@latest

Or download a binary from Releases.

Usage as a Library

bits can be used as a Go library to build your own crypto tools. Import github.com/mdnmdn/bits.

Multi-Provider Client

import (
	"context"
	"fmt"
	"github.com/mdnmdn/bits"
	"github.com/mdnmdn/bits/config"
	"github.com/mdnmdn/bits/model"
)

func main() {
	cfg := &config.Config{
		Binance: config.BinanceConfig{
			Spot: config.MarketConfig{Enabled: true},
		},
	}

	// Multi-provider client with symbol resolution
	client := bits.NewClient(cfg, bits.WithSymbolEngine())

	// Get price with automatic symbol resolution
	price, _ := client.GetPriceWithResolution(context.Background(), "BTC-USDT", "binance", model.MarketSpot)
	fmt.Printf("BTC Price: %.2f\n", price.Data.Price)

	// Compare prices across exchanges
	results, _ := client.ComparePricesWithResolution(context.Background(), "BTC-USDT",
		[]string{"binance", "bitget", "whitebit"}, model.MarketSpot)
	for _, r := range results {
		fmt.Printf("%s: $%.2f\n", r.Provider, r.Data.Price)
	}
}

Provider-Specific Client (Stateful)

For stateful operations like WebSocket streaming, create a client locked to a specific provider:

cfg := &config.Config{
	Binance: config.BinanceConfig{Spot: config.MarketConfig{Enabled: true}},
}

p := bits.NewProvider(cfg, "binance")

// Direct method calls - transparent to implementation
p.Price(ctx, []string{"BTCUSDT"}, "")
p.Ticker24h(ctx, "BTCUSDT", "spot")
p.Candles(ctx, "BTCUSDT", "spot", "1h", nil)
p.OrderBook(ctx, "BTCUSDT", "spot", 10)

// WebSocket streaming (stateful)
p.StartPriceStream(ctx, []string{"bitcoin"})
p.StartOrderBookStream(ctx, []string{"BTCUSDT"}, "spot", 10)

// Capabilities
p.ID()
p.Capabilities()

When a provider doesn't support a capability (e.g., Binance has no PriceStream), the method returns a "not implemented" error instead of panicking.

Symbol Normalization

// Works without the symbol engine
bits.NormalizeSymbol("BTCUSDT")  // "BTC-USDT"
bits.NormalizeSymbol("BTC_USDT") // "BTC-USDT"

Run examples:

go run ./examples/basic_usage
go run ./examples/price_comparison
go run ./examples/symbol_resolution

Setup

Config file: ~/Library/Application Support/bits-cli/config.yaml (macOS) or ~/.config/bits/config.yaml (Linux).

provider: coingecko

[coingecko]
api_key: ""
tier: demo        # demo | paid

[binance]
api_key: ""
api_secret: ""

[bitget]
api_key: ""
api_secret: ""
passphrase: ""

All values accept BITS_* environment variable overrides:

BITS_PROVIDER=binance
BITS_COINGECKO_API_KEY=your_key   BITS_COINGECKO_TIER=paid
BITS_BINANCE_API_KEY=your_key     BITS_BINANCE_API_SECRET=your_secret
BITS_BITGET_API_KEY=your_key      BITS_BITGET_API_SECRET=your_secret   BITS_BITGET_PASSPHRASE=your_pass

Command reference

Global flags

-p, --provider       string   coingecko | binance | bitget  (default: from config)
-m, --market         string   spot | futures | margin        (default: spot)
-o, --output         string   table | json | yaml | markdown | toon  (default: table)
-f, --allow-fallback          allow fallback even when --provider is set

`bits price`

Current price for one or more coin IDs (CoinGecko) or symbols (exchanges). Batch-native — one API call regardless of how many IDs you pass.

bits price bitcoin ethereum
bits price bitcoin --currency eur
bits price BTCUSDT ETHUSDT -p binance -m futures
bits price bitcoin -o toon

`bits ticker`

24h rolling stats — last price, change %, high, low, volume. Multi-symbol calls fan out in parallel; partial failures don't abort the rest.

bits ticker BTCUSDT -p binance
bits ticker BTCUSDT ETHUSDT SOLUSDT -p binance
bits ticker BTCUSDT -p binance -m futures -o json

`bits book`

Order book depth snapshot — bids and asks side by side.

bits book BTCUSDT -p binance
bits book BTCUSDT -p binance --depth 100
bits book BTCUSDT -p binance -m futures -o yaml

`bits candles`

OHLCV candle history with flexible time range.

bits candles BTCUSDT -p binance --interval 1h
bits candles BTCUSDT -p binance -m futures --from 2024-01-01 --to 2024-06-01
bits candles bitcoin --limit 100 -o json

Flag	Default	Description
`--interval`	`1h`	`1m` `5m` `1h` `4h` `1d` etc.
`--from`	—	RFC3339 or `YYYY-MM-DD`
`--to`	—	RFC3339 or `YYYY-MM-DD`
`--limit`	—	Max candles (0 = provider default)

`bits time`

Exchange server time with computed round-trip latency and clock skew. Exchanges only (Binance, Bitget).

bits time -p binance
bits time -p bitget -o json

`bits info`

Full symbol catalogue for an exchange. Use --symbol to filter.

bits info -p binance
bits info -p binance -m futures
bits info -p binance --symbol BTCUSDT

`bits markets`

Ranked coin list by market cap. CoinGecko only (aggregator feature); automatically routed there.

bits markets
bits markets --currency eur --per-page 50
bits markets --page 3 -o yaml

`bits stream price`

Live WebSocket price feed — CoinGecko paid plan required. One update per line; Ctrl+C to stop.

bits stream price bitcoin ethereum
bits stream price bitcoin -o json | jq .price    # pipe prices
bits stream price bitcoin -o yaml                # YAML docs, --- separated
bits stream price bitcoin -o toon                # colored live lines

`bits stream book`

Live WebSocket order book feed — Binance only. One update per line; Ctrl+C to stop.

bits stream book BTCUSDT -p binance
bits stream book BTCUSDT -p binance --depth 5
bits stream book BTCUSDT -p binance -o json      # JSONL

`bits providers`

List all registered providers and which one is currently active.

bits providers

`bits capabilities` / `bits caps`

The capability matrix: which features each provider supports, by market type. No API key needed.

bits capabilities
bits caps -p binance

Development

make build    # → ./bits
make test     # go test -race ./...
make lint     # golangci-lint

Tech Stack

Package	Purpose
cobra	CLI framework
viper	Config (YAML + env vars)
go-binance/v2	Binance HTTP client
gorilla/websocket	WebSocket streaming
lipgloss	Terminal styling (`toon` format)
goreleaser	Cross-platform release builds

License

MIT — see LICENSE.

Name		Name	Last commit message	Last commit date
Latest commit History 185 Commits
.claude		.claude
.github/workflows		.github/workflows
_docs		_docs
_tools		_tools
capability		capability
cmd		cmd
command		command
config		config
examples		examples
internal		internal
model		model
process		process
provider		provider
render		render
resolve		resolve
.gitignore		.gitignore
.goreleaser.yml		.goreleaser.yml
AGENTS.md		AGENTS.md
CLAUDE.md		CLAUDE.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
bits		bits
client.go		client.go
config.sample.env		config.sample.env
config.sample.toml		config.sample.toml
config.sample.yaml		config.sample.yaml
go.mod		go.mod
go.sum		go.sum
install.sh		install.sh

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

bits

What it does

Providers

Output formats

Install

Usage as a Library

Multi-Provider Client

Provider-Specific Client (Stateful)

Symbol Normalization

Setup

Command reference

Global flags

`bits price`

`bits ticker`

`bits book`

`bits candles`

`bits time`

`bits info`

`bits markets`

`bits stream price`

`bits stream book`

`bits providers`

`bits capabilities` / `bits caps`

Development

Tech Stack

License

About

Uh oh!

Releases 3

Contributors

Uh oh!

Languages

Folders and files

Latest commit

History

Repository files navigation

bits

What it does

Providers

Output formats

Install

Usage as a Library

Multi-Provider Client

Provider-Specific Client (Stateful)

Symbol Normalization

Setup

Command reference

Global flags

bits price

bits ticker

bits book

bits candles

bits time

bits info

bits markets

bits stream price

bits stream book

bits providers

bits capabilities / bits caps

Development

Tech Stack

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 3

Contributors

Uh oh!

Languages

`bits price`

`bits ticker`

`bits book`

`bits candles`

`bits time`

`bits info`

`bits markets`

`bits stream price`

`bits stream book`

`bits providers`

`bits capabilities` / `bits caps`