Wallbit Workflow Builder

wallbit-cli workflow builder

Wallbit-cli runs declarative YAML workflows that call the Wallbit API through a fixed registry of 15 run ids. This skill produces specs that pass wallbit workflow validate and execute as expected with wallbit workflow run.

Quick start

Minimum valid spec (saved as wf.yaml):

version: 1
name: my-workflow
steps:
  - id: bal
    run: balance.get_checking

Validate, then run:

wallbit workflow validate wf.yaml
wallbit workflow run wf.yaml

Top-level fields

on_error: fail_fast stops at the first failing step. on_error: continue runs every step regardless; the final result is ok: false if any step failed.

Step fields

Run catalog

Use this only as an index. For required/optional with keys per run, open the matching reference file.

The Shape column tells you what the run output looks like and therefore which ${steps.<id>.…} paths are reachable:

• obj — data.Data is a single struct. Fields are reachable directly under data.Data.<Field>.
• slice — data.Data is []Something. Not indexable from refs (no [0]).
• paged-flat — pagination metadata sits alongside the slice, one level deep: data.Pages, data.CurrentPage, data.Count, and data.Data (the slice). Currently only assets.list.
• paged-nested — pagination metadata sits inside a Data wrapper, two levels deep: data.Data.Pages, data.Data.CurrentPage, data.Data.Count, and data.Data.Data (the slice). Currently only transactions.list.

In every case the slice itself cannot be indexed from a ref. Always confirm exact paths against references/runs-reads.md for the run you are using.

Reads — see references/runs-reads.md for inputs and field paths:

Writes / mutations — see references/runs-writes.md:

Cross-step references

Inside any with value, use ${steps.<step_id>.<path>} to read from a prior step's result. Example:

- id: fx
  run: rates.get
  with:
    source: USD
    dest: EUR

- id: account
  run: account_details.get
  with:
    currency: ${steps.fx.data.Data.SourceCurrency}

Two non-obvious rules trip everyone the first time:

1. The path walks Go struct field names (case-insensitive), not JSON keys, so it is data.Data.SourceCurrency, not data.data.source_currency.
2. Array indexing is not supported (no data[0]).

For the full ref grammar, descent rules, standalone vs embedded modes, and per-run available paths, read references/step-refs.md.

Validate before running

Always run validation first — it catches every static error (unsupported run, missing required with keys, duplicate ids, bad on_error, wrong version) without touching the API:

wallbit workflow validate path/to/wf.yaml

The validator exits non-zero on failure and prints the offending step index and reason.

Validate does NOT resolve ${steps.<id>.<path>} references. A wrong path (typo, missing field, indexing into a slice) passes validate and only surfaces at run time as reference steps.<id>.<path> not found, failing the step. To catch ref bugs before production, do a smoke run against a dev account.

Output shape

validate and run emit different JSON shapes. Both go to stdout pretty-printed.

wallbit workflow validate wf.yaml (small summary, no API calls):

{ "name": "my-workflow", "ok": true, "steps": 2, "version": 1 }

wallbit workflow run wf.yaml (full execution result):

{
  "workflow": "my-workflow",
  "ok": true,
  "started_at": "...",
  "finished_at": "...",
  "failed_step_id": "",
  "steps": [
    {
      "id": "bal",
      "run": "balance.get_checking",
      "ok": true,
      "data": { "...": "raw service payload" },
      "duration_ms": 123
    }
  ]
}

Note: the name field becomes workflow in the run output. On failure: ok: false, failed_step_id is set, and the failing step has error.message instead of data. Pipe to jq for ad-hoc inspection.

Critical pitfalls

1. trades.create requires exactly one of amount (notional in currency) or shares (quantity). Providing both, or neither, fails validation.
2. roboadvisor.deposit / roboadvisor.withdraw: from / to must be the literal string DEFAULT or INVESTMENT, and amount must be > 0.
3. cards.block / cards.unblock: card_uuid must be a real UUID string. You cannot pull it from ${steps.cards_list.data.data[0].uuid} — array indexing is unsupported. Either hardcode the UUID or split the workflow.
4. apikey.revoke is destructive — it invalidates the API key currently in use. Comment it out in any shareable example.

Common patterns and recipes

For idiomatic patterns (chained reads, safe dev smoke tests, multi-balance snapshots, validate-then-run pre-flight), see references/recipes.md.

Authoring checklist

Before handing the file back to the user:

• version: 1 set, name set.
• Every step id is unique.
• Every run is in the catalog above.
• All required with keys per run are present (check the reference file).
• ${steps.…} paths reference only prior steps, use Go field names, no [index].
• Mutations use small/safe values or are commented out by default.
• wallbit workflow validate passes locally if the env is set up.