crypto-tools

Coinbase operations toolkit: cb for trade planning and order lifecycle management, hdb for ledger ingestion/reconciliation and tax-facing analytics, hdb-portal for local read-only web analysis, plus shared TypeScript modules for authenticated API access and reusable CLI infrastructure.

What is here

• cb: trading operations CLI (quotes, sizing, plan workflows, order lifecycle) (src/apps/cb)
• hdb: accounting/data CLI (imports, snapshots, lots, reconciliation, exports) (src/apps/hdb)
• hdb-portal: local web portal for hdb analysis (src/apps/hdb-portal)
• shared: reusable Coinbase/auth/env/log/schema modules (src/shared)
• helper-env-check: env/credential validation binary (src/shared/bin/validate-env.ts)

Imports

Use explicit relative imports with .js specifiers under NodeNext.

Requirements

• Node.js >=20
• npm

Quick Start

npm ci
npm run build
npm link
export PATH="$(npm prefix -g)/bin:$PATH"
command -v cb hdb helper-env-check
cb --help
hdb --help
helper-env-check --help

npm link installs the command symlinks under $(npm prefix -g)/bin. If the commands are not found after linking, add that directory to PATH in your shell startup file, then open a new shell. If npm link reports a permissions error, configure a user-owned npm prefix rather than running it with sudo.

Configure the application after verifying the binaries:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}/helper"
cp .env.example "${XDG_CONFIG_HOME:-$HOME/.config}/helper/.env"

Set this value in the env file:

HELPER_COINBASE_CREDENTIALS_PATH=/absolute/path/to/coinbase-credentials.json
HELPER_POSTGRES_DATABASE=hdb
HELPER_POSTGRES_USERNAME=hdb_user
HELPER_POSTGRES_PASSWORD=replace-with-a-local-password

Create Coinbase App API credentials using: https://docs.cdp.coinbase.com/coinbase-app/authentication-authorization/api-key-authentication

When creating the key in CDP, select the ECDSA signature algorithm (ES256). Live Coinbase requests remain disabled unless HELPER_ALLOW_LIVE_EXCHANGE=true is explicitly set.

The PostgreSQL values are required by hdb and hdb-portal, but not by cb. See src/apps/hdb/README.postgres.md for local database creation instructions.

Running CLIs

• cb --help
• hdb --help
• helper-env-check --help
• npm run dev:hdb-portal (the portal is not installed as a linked binary)

From source:

• npm run dev -- --help (runs cb)
• npm run dev:hdb -- --help (runs hdb)

Machine-readable CLI output:

• prefer cb ... --json and hdb ... --json when you want structured output for automation or agent workflows
• use --json-file <path> on read-only inspection commands that expose it when you want the same payload written to disk

Documentation

• cb CLI README
• src/apps/hdb/README.md
• src/apps/hdb/README.postgres.md
• src/apps/hdb-portal/README.md
• src/shared/README.md
• CONTRIBUTING.md

Quality Checks

npm run lint
npm run typecheck
npm run test
npm run build

Integration smoke checks (readonly mode + sanitized env):

npm run test:integration:smoke

Override readonly env file path when needed:

INTEGRATION_ENV_FILE=/absolute/path/to/.env.readonly npm run test:integration:smoke

License

Apache-2.0