Documentation

Prerequisites

• Go toolchain (to install with go install)
• A Wallbit API key
• Network access to your Wallbit API host (default base URL is production unless you override with --base-url)

Installation

Install the wallbit binary from the repository module path:

go install github.com/jeremyjsx/wallbit-cli/cmd/wallbit@latest

Put the Go bin directory on your PATH so your shell can run wallbit. With a default go install, that directory is usually $(go env GOPATH)/bin (or wherever you install binaries).

Authentication

The CLI resolves an API key in this order: --api-key flag, then WALLBIT_API_KEY, then the local credentials file written by wallbit auth login.

Global flags

These flags are available on the root command and inherited by subcommands.

CLI reference

All successful commands write JSON to stdout unless noted. Errors are printed to stderr and exit non-zero.

auth

See Authentication above. Subcommands: login, status, logout.

Command overview

Most commands are thin wrappers over one API domain. Use this table as a fast map, then jump to workflows when you need multi-step execution.

trades

wallbit trades create — Required: --symbol, --direction (BUY or SELL), --order-type (MARKET, LIMIT, STOP, STOP_LIMIT). Exactly one of --amount or --shares. Optional: --currency (default USD), --stop-price, --limit-price, --time-in-force (DAY or GTC for LIMIT).

LIMIT requires --limit-price and --time-in-force. STOP requires --stop-price. STOP_LIMIT requires both stop and limit prices.

For the remaining groups (roboadvisor, fees, apikey), prefer workflow handlers when available and use direct commands for operational one-offs.

Environment

First workflow in 5 minutes

Your fastest path is: create a YAML file, validate it, then run it. Use this as a copy-paste baseline:

version: 1
name: quickstart-fx
steps:
  - id: fx
    run: rates.get
    with:
      source: USD
      dest: EUR
  - id: wallets
    run: wallets.get
    with:
      currency: USDC
      network: polygon

wallbit workflow validate ./quickstart.yaml
wallbit workflow run ./quickstart.yaml

Workflow language

Workflows are plain YAML with ordered steps. Each step has an id, a run key, and optional with inputs. Use step references to build multi-step logic: ${steps.<step_id>.<dot.path>} .

Patterns cookbook

Pattern 1 - FX check plus reverse confirmation

version: 1
name: fx-roundtrip
steps:
  - id: base_fx
    run: rates.get
    with:
      source: USD
      dest: EUR
  - id: reverse_fx
    run: rates.get
    with:
      source: ${steps.base_fx.data.Data.DestCurrency}
      dest: ${steps.base_fx.data.Data.SourceCurrency}

Pattern 2 - Portfolio context plus transaction scan

version: 1
name: portfolio-scan
steps:
  - id: wallets
    run: wallets.get
    with:
      currency: USDC
      network: polygon
  - id: tx
    run: transactions.list
    with:
      page: 1
      limit: 10
      currency: USD

Pattern 3 - Multi-domain snapshot

version: 1
name: morning-snapshot
steps:
  - id: assets
    run: assets.list
    with:
      page: 1
      limit: 5
      category: TECHNOLOGY
  - id: cards
    run: cards.list

AI prompt templates

Give your copilot strict prompts so it emits runnable YAML instead of vague prose.

Generate a wallbit-cli workflow YAML (version 1) with:
- 3 steps
- one rates.get step (USD -> EUR)
- one wallets.get step (USDC on polygon)
- one transactions.list step (limit 10)
Return only valid YAML, no markdown, no explanations.

Refactor this workflow to use step references where possible.
Keep run keys valid for wallbit-cli.
Return only YAML.

<paste-workflow-here>

YAML workflow specification

Top-level fields:

Each step:

version: 1
name: example
on_error: fail_fast
steps:
  - id: usd_eur
    run: rates.get
    with:
      source: USD
      dest: EUR
  - id: list_tx
    run: transactions.list
    with:
      limit: 20

Validate, Run & Output

Both commands parse YAML, run structural validation (version, unique id, non-empty run, valid on_error), then ValidateSupportedRuns and ValidateStepInputs. run additionally executes each step in order.

workflow

YAML workflow runner.

• wallbit workflow validate <file.yaml> — Parse YAML, ensure version and structure, check every run is supported, validate with for steps that have validators. Prints a small JSON summary on success.
• wallbit workflow run <file.yaml> — Same validation as above, then executes steps in order and prints JSON RunResult (see Output format).

Output format

Commands that call the API print indented JSON. workflow run prints a RunResult: workflow, ok, started_at, finished_at, optional failed_step_id, and steps. Each step has id, run, ok, optional data (API payload), optional error with message, and duration_ms.

Step output references

In with values you can interpolate prior step results using ${steps.<step_id>.<dot.path>}. The path walks struct fields (case-insensitive) or map keys. If the entire with value is a single reference, the resolved type is preserved; otherwise references are stringified into the template.

Only steps that completed successfully before the current step are visible; references must match a prior id.

Workflow step catalog

Each row is a run key. Fields listed under with use workflow YAML naming (snake_case).

Want more workflow recipes, integrations, or step patterns? Open an issue and share your use case so we can prioritize it in the docs and examples. You can also explore the repository and create a request directly in issues.