Skip to content

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
FieldTypeRequiredDescription
BANKR_API_KEYenv (server-only)yesBankr Agent API key. Read exclusively on the server; errors that mention it are redacted.
BANKR_AGENT_IDenv (server-only)noOptional: route prompts to a specific Bankr agent.
BANKR_BASE_URLenv (server-only)noOptional API base override. Defaults to https://api.bankr.bot.
AI_PROVIDERenv (server-only)nomock | 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).

How output becomes a manifest

  1. Extract the first plausible JSON object (fenced ```json block or bare braces) from the agent's text.
  2. Drop allocations whose tickers aren't in the canonical registry; deduplicate the rest.
  3. Renormalize surviving weights to exactly 10,000 bps.
  4. Rebuild a full manifest (creator source bankr-agent) and run guardrail validation.
  5. 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

Troubleshooting

  • 403 with subscription_required: the Bankr Agent API rejects prompts unless the Bankr account has Bankr Club or Max Mode LLM credits. A valid API key alone is not enough — upgrade the Bankr account, or run with the mock fallback until then. HISS surfaces this as BANKR_HTTP_ERROR with the subscription hint in the message.
  • BANKR_TIMEOUT: prompt + polling exceeded the deadline (default 25s). Jobs occasionally run long; in bankr_or_mock mode the mock answer is served instead.
  • BANKR_INVALID_OUTPUT: the agent's reply had no parseable manifest, or no canonical assets survived repair. Usually a prompt-format regression — check that the agent echoes the required JSON shape.
  • bankrConfigured: false in /api/health: the key isn't reaching the server process. Check the deployment env, not the client env.

$HISS is independent research software in paper mode — not investment advice, and not affiliated with Robinhood, Bankr, or Chainlink.