@covalenthq/goldrush-cli

Terminal-first algorithmic trading CLI powered by GoldRush API. Built in TypeScript with a proxy server pattern for rich terminal UI alongside Claude MCP integration.

Quick Start

pnpm setup #export PNPM_HOME
pnpm install #installs dependencies
pnpm build #builds the package

pnpm link --global # /Users/<username>/Library/pnpm/global/5: + @covalenthq/goldrush-cli 3.0.6 <- ../../../../Documents/covalent/goldrush-services-monorepo/services/goldrush-cli

pnpm --filter @covalenthq/client-sdk build #builds the client-sdk package
pnpm --filter @covalenthq/goldrush-cli build #builds the goldrush-cli package

# Set up your API key
goldrush auth

# Check token balances
goldrush balances eth-mainnet 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045

# Stream new DEX pairs
goldrush new_pairs eth-mainnet

# Launch proxy server (for MCP bridge)
goldrush proxy

# Configure Claude MCP integration
goldrush install

Commands

| Command | Purpose | | -------------------------------------- | ------------------------------------ | | goldrush | Interactive menu | | goldrush auth | Set up API key + service key | | goldrush balances [chain] [address] | Token balances with rich table | | goldrush transfers [chain] [address] | Transfer history | | goldrush nfts [chain] [address] | NFT holdings for a wallet | | goldrush new_pairs [chain] | Stream new DEX pairs | | goldrush ohlcv_pairs [chain] [pair] | OHLCV pairs stream | | goldrush search [chain] [query] | Token search | | goldrush traders [chain] [token] | Top traders | | goldrush gas [chain] | Gas prices | | goldrush chains | List supported chains | | goldrush watch [chain] [address] | Watch wallet activity | | goldrush proxy | Launch proxy server | | goldrush mcp | MCP stdio bridge (invoked by Claude) | | goldrush install | Configure Claude MCP integration | | goldrush config | View/edit settings | | goldrush status | Check connectivity | | goldrush usage | Account credit usage & limits | | goldrush logout | Clear credentials |

All positional args are optional — when omitted the CLI falls back to the configured default chain (goldrush config) and prompts interactively for the missing identifier.

Authentication & keys

The CLI works with two distinct credentials:

| Key | Used for | Set via | | --------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | API key | The regular GoldRush data API (balances, transfers, gas, …) | goldrush auth, goldrush auth --api-key <key>, or GOLDRUSH_API_KEY | | Service key | Service-key-gated /platform/* endpoints — currently goldrush usage | goldrush auth --service-key <key>, goldrush config → Service Key, or GOLDRUSH_SERVICE_KEY |

The two keys are stored separately (OS keychain when available, otherwise the local config file) and setting one never overwrites the other. Running goldrush auth with no flags walks you through the API key and then offers to set a service key. Get keys from the GoldRush platform.

# Interactive (prompts for both)
goldrush auth

# Non-interactive, each key independently
goldrush auth --api-key <goldrush-api-key>
goldrush auth --service-key <service-key>

For single-key setups, goldrush usage falls back to your regular API key when no dedicated service key is configured, so it keeps working out of the box.

Account usage

goldrush usage reports your credit consumption, billing cycle, rate limit and flex-credit status. It calls the service-key-gated usage endpoint on api.covalenthq.com (separate from the regular data API). The service key is read from the OS keychain, the GOLDRUSH_SERVICE_KEY environment variable, or — for single-key setups — your regular GoldRush API key. Advanced overrides:

• GOLDRUSH_API_URL — base URL for service-key endpoints (default https://api.covalenthq.com)
• GOLDRUSH_USAGE_PATH — usage endpoint path (default /platform/usage/)

Architecture

Claude Desktop/Code <--stdio--> MCP Bridge <--HTTP--> Proxy Server <--HTTP--> Hosted MCP Server
                                (goldrush mcp)        (goldrush proxy)        (goldrush-mcp.vercel.app)

The proxy server fetches tool definitions and forwards tool calls to the hosted MCP server (configurable via GOLDRUSH_MCP_URL). The MCP bridge translates between stdio (for Claude) and HTTP (for the proxy), keeping terminal UI output separate from the MCP protocol.

Development

pnpm dev           # Run with tsx
pnpm build         # Build with tsup
pnpm test          # Run tests
pnpm typecheck     # TypeScript check