capitalcom-cli

Capital.com REST API client & CLI — trade CFDs from the command line.

Built with Bun. Zero dependencies.

Features

• Session-based auth with automatic re-login on 401
• Token-bucket rate limiter (10 req/s, Capital.com's limit)
• Circuit breaker (5 consecutive failures → 60 s cooldown)
• URL normalization — accepts any base URL format
• Dual-use: CLI tool and importable TypeScript library

Quick start

# Clone
git clone https://github.com/youruser/capitalcom-cli.git
cd capitalcom-cli

# Configure
cp .env.example .env
# Edit .env with your Capital.com API credentials

# Run
bun run src/cli.ts login
bun run src/cli.ts accounts

Or install globally:

bun link           # registers the 'capitalcom' binary
capitalcom login

Commands

Command	Description
login	Test authentication
accounts	List accounts with balances
positions	List open positions with live P&L
price <epic>	Live bid/offer/spread quote
market <epic>	Full market info (JSON)
prices <epic>	Historical OHLC candles
search <term>	Search markets by keyword
open	Open a position
close <dealId>	Close a position

Examples

# Market data
capitalcom price US100
capitalcom prices EURUSD --resolution HOUR --max 24
capitalcom search "natural gas"

# Trading
capitalcom open --epic AAPL --direction BUY --size 1 --stop 150 --profit 200
capitalcom close DIAAAAA1234567

# Portfolio
capitalcom accounts
capitalcom positions

Price resolutions

MINUTE MINUTE_5 MINUTE_15 MINUTE_30 HOUR HOUR_4 DAY WEEK

Use as a library

import { login, apiRequest } from "capitalcom-cli";

await login();

const { accounts } = await apiRequest("GET", "/accounts");
console.log(accounts[0].balance);

const quote = await apiRequest("GET", "/markets/US100");
console.log(quote.snapshot.bid, quote.snapshot.offer);

Environment variables

Variable	Required	Description
CAPITAL_COM_API_KEY	Yes	API key from Capital.com
CAPITAL_COM_USER	Yes	Login email / identifier
CAPITAL_COM_PSW	Yes	Password
CAPITAL_COM_URL	No	Base URL (defaults to demo API)

Set CAPITAL_COM_URL to https://api-capital.backend-capital.com/api/v1 for live trading.

Architecture

src/
  cli.ts             CLI entry point & router
  index.ts           Public library exports
  client.ts          API client (auth, request, retry)
  commands.ts        Command implementations
  config.ts          Environment / URL config
  rate-limiter.ts    Token-bucket rate limiter
  circuit-breaker.ts Circuit breaker (closed/open/half-open)

License

MIT