Bankr integration

operator

Configure the Bankr strategist brain: env vars, fallback, troubleshooting.

What Bankr does in HISS

When configured, the Bankr Agent API is the Strategist's brain: HISS wraps the user's whisper in a manifest-shaped instruction, submits it via POST {base}/agent/prompt (authenticated with an X-API-Key header), then polls GET {base}/agent/job/{jobId} until the job completes. The agent's free-text answer is parsed for a manifest JSON block, repaired to the canonical registry, renormalized to 10,000 bps, and passed through the same guardrails as every other agent output. Bankr proposes; HISS validates. Nothing Bankr returns can execute anything.

Server-side configuration

Bankr environment variables
Field	Type	Required	Description
BANKR_API_KEY	env (server-only)	yes	Bankr Agent API key. Read exclusively on the server; errors that mention it are redacted.
BANKR_AGENT_ID	env (server-only)	no	Optional: route prompts to a specific Bankr agent.
BANKR_BASE_URL	env (server-only)	no	Optional API base override. Defaults to https://api.bankr.bot.
AI_PROVIDER	env (server-only)	no	mock \| bankr \| bankr_or_mock. Defaults to bankr_or_mock.

.env (server)

# Server-only — set these in your deployment environment, never in code.
AI_PROVIDER=bankr_or_mock       # or "bankr" (strict) / "mock"
BANKR_API_KEY=bk_…              # required for any Bankr mode
BANKR_AGENT_ID=…                # optional: pin a specific Bankr agent
BANKR_BASE_URL=https://api.bankr.bot   # optional override

Provider modes and fallback

bankr_or_mock (the default) uses Bankr when a key is present and falls back to the deterministic mock on any failure — missing key, HTTP error, timeout, unparseable output, or guardrail rejection — so a user's prompt is never lost. The response's providerMeta.usedFallback and fallbackReason report what happened. Strict bankr mode surfaces errors to the caller instead (typed codes: BANKR_NOT_CONFIGURED, BANKR_HTTP_ERROR, BANKR_TIMEOUT, BANKR_INVALID_OUTPUT, GUARDRAIL_REJECTED).

Provider mode matrix

AI_PROVIDER	Key required	On Bankr failure	Best for
`mock`	no	n/a — Bankr never called	Local dev, CI, deterministic demos.
`bankr`	yes	Typed error surfaced to the caller (503/502)	Verifying the Bankr path itself; strict staging.
`bankr_or_mock` (default)	optional	Silent fallback to mock; `providerMeta.usedFallback: true`	Production: prompts never lost, provider always reported.

How output becomes a manifest

Extract the first plausible JSON object (fenced ```json block or bare braces) from the agent's text.
Drop allocations whose tickers aren't in the canonical registry; deduplicate the rest.
Renormalize surviving weights to exactly 10,000 bps.
Rebuild a full manifest (creator source bankr-agent) and run guardrail validation.
Score it and attach memo, risk summary, and disclaimers — identical to the mock path.

Testing locally

You don't need a Bankr account to develop against the Strategist — set AI_PROVIDER=mock and every response is deterministic:

local testing

# Local development without any Bankr account:
AI_PROVIDER=mock pnpm --filter @hiss/web dev

# Then exercise the endpoint:
curl -s localhost:3000/api/agent/hiss \
  -H "content-type: application/json" \
  -d '{"prompt": "Defensive cashflow basket"}' | jq .providerMeta

Health check

GET /api/health reports safe metadata only — flags and booleans, never secret values. Use it to confirm the key reached the server process before debugging anything else. GET /api/agent/hiss returns the same aiProvider / bankrConfigured pair scoped to the Strategist.

health-check flow

curl -s localhost:3000/api/health | jq '{ok, aiProvider, bankrConfigured, x402: .x402.mode, flags}'
# {
#   "ok": true,
#   "aiProvider": "bankr_or_mock",
#   "bankrConfigured": true,
#   "x402": "disabled",
#   "flags": { "liveTrading": false, "vaultDeposits": false, "mcpMode": true, "mocks": true }
# }

ok / service / mode — liveness; mode is always paper today.
aiProvider — the resolved provider mode (mock | bankr | bankr_or_mock).
bankrConfigured — whether BANKR_API_KEY is present in the server env.
x402.mode — disabled (free mock envelopes) or mock-unverified.
flags — live trading, vaults, MCP mode, and mocks; live flags are off by default.

Troubleshooting

Expected errors, what they mean, and the fix:

Symptom	Meaning	Fix
403 `subscription_required` (from Bankr)	Bankr’s docs are explicit: “Bankr requires either a Bankr Club subscription or Max Mode (LLM credits) to use” — there is no free tier, and a valid API key alone is not enough.	Upgrade the Bankr account (Bankr Club: unlimited chat on the default Gemini Flash model; Max Mode: LLM credits with `--model` override), or run on the mock fallback until then. Surfaced as `BANKR_HTTP_ERROR`.
`BANKR_TIMEOUT`	Prompt + job polling exceeded the deadline (default 25s).	Nothing usually — in `bankr_or_mock` the mock answer is served with `fallbackReason` set. Retry for a Bankr answer.
`BANKR_INVALID_OUTPUT`	The agent’s reply had no parseable manifest, or no canonical assets survived repair.	Repairable replies are repaired automatically (registry filter + renormalize to 10,000 bps); truly unusable ones are rejected. Check the agent echoes the JSON shape.
`GUARDRAIL_REJECTED`	The parsed manifest failed HISS validation even after repair.	Inspect the prompt for rule-breaking asks (non-canonical assets, live execution).
`BANKR_NOT_CONFIGURED` (503)	Strict `bankr` mode without a key in the server env.	Set `BANKR_API_KEY` in the deployment env, or use `bankr_or_mock`.

bankrConfigured: false in /api/health: the key isn't reaching the server process. Check the deployment env, not the client env.

Ecosystem notes

LLM Gateway plugins: Bankr ships official Claude Code / Codex / Cursor plugins (bankr-agent, bankr-x402-sdk-dev) for its LLM Gateway.
TEE private inference: the Gateway supports private inference via a :private model suffix.
Agent Profiles: Bankr exposes public agent pages at bankr.bot/agents — the natural counterpart to HISS Agent Passports.
x402 Cloud: now fully documented (bankr.x402.json config, no monthly fees, USDC-on-Base default with any ERC-20 configurable). Deploying HISS paid endpoints on x402 Cloud is the likely path to verified settlement — not enabled today; every x402 response remains mock/disabled-labeled. See x402 payments.