Skip to content

API reference

developerreadiness check

Endpoints, request/response envelopes, and copy-paste examples.

Base URL and auth

All endpoints live under https://app.hiss.finance. Compilation, validation, and readiness endpoints are open and rate limited; wallet-scoped endpoints (/api/me/*) require a SIWE wallet session. No endpoint accepts credentials, API keys, seed phrases, or brokerage logins — credential-shaped fields are rejected before processing. POST bodies are capped at 256 KB.

Route families

Route families
MethodPathModeDescription
POST/api/tools/*freeCoilOps tools: generate, validate, score, compile capsules, audit fuses, drift checks, receipts. Full docs in Agent tools API.
POST/api/bankrbot/*freeBankrbot → Robinhood MCP autonomy path: compile, validate autonomy fuses, command packs, post-run audits. Schema at GET /api/bankrbot/schema.
GET/POST/api/vaults/*freeUSDG vault flows on Robinhood Chain: manifests, deposit/withdraw intents (deposit-readiness gated), rebalance policies, receipts, asset registry, readiness.
GET/POST/api/x402/*livex402 payment lanes: provider directory, Bankr (Base) and Meridian (Robinhood Chain) status, settlement (when configured).
GET/POST/api/auth/*liveSIWE wallet sessions: nonce, verify, session, logout. Never seed phrases or private keys.
GET/api/me/*authWallet-scoped resources: your saved Coils and receipts. 401 without a session.
GET/api/readinessliveProduction readiness: database, chain health, x402 providers, deployment commit. States only, never values.
GET/api/healthliveService mode and feature-flag status. Safe metadata only.

Deep documentation per family: Agent tools API, Bankrbot × Robinhood, USDG Vaults, and x402 payment architecture.

Response conventions

Tool and autonomy responses carry notInvestmentAdvice: true and liveOrderSent: false on every payload, plus deterministic receipts where the operation produces an artifact. Vault and x402 responses additionally separate vaultChain (always Robinhood Chain) from x402PaymentChain (Base for Bankr Cloud, Robinhood Chain for Meridian when configured), and include sourceVerification blocks with last-verified dates. An output guard blocks any response that reads like an execution claim.

Error envelope

errors
// Validation / input errors (400, 404, 409, 422):
{ "error": { "code": "…", "message": "…", "issues": [ { "code": "…", "message": "…" } ] } }

// Strategist failures (502/503) — your prompt is echoed back so no input is lost:
{ "error": "The strategist could not complete this request. Your prompt was not lost — try again.",
  "code": "BANKR_TIMEOUT", "prompt": "the original prompt" }

POST /api/agent/hiss

The AI Strategist: whisper in, validated manifest out. GET on the same path returns provider status metadata. When no external provider is configured, the deterministic local strategist answers and providerMeta.provider says so — outputs are always labeled with their provenance.

agent/hiss request fields
FieldTypeRequiredDescription
promptstringyesThe market whisper. Max 2000 characters.
mode"paper" | "brokerage-mcp-plan"noPlanning mode. Defaults to the readiness-check planner.
basketContextPartial<Manifest>noExisting basket to refine instead of starting fresh.
userPreferencesobjectnomaxSingleAssetWeightBps and riskTolerance (low/medium/high).
curl
curl -s https://app.hiss.finance/api/agent/hiss \
  -H "content-type: application/json" \
  -d '{"prompt": "AI infra without full NVDA concentration"}'
typescript
const res = await fetch("https://app.hiss.finance/api/agent/hiss", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    prompt: "AI infra without full NVDA concentration",
    userPreferences: { maxSingleAssetWeightBps: 3000 },
  }),
});
if (!res.ok) throw new Error(`strategist failed: ${res.status}`);
const { manifest, score, providerMeta } = await res.json();
console.log(manifest.name, score.total, providerMeta.provider);

GET /api/health

Service mode and feature-flag status. Safe metadata only — never secret values. Registry and oracle-policy versions in force are stamped into every receipt.

curl
curl -s https://app.hiss.finance/api/health

Discovery endpoints

Agents should start from the schema routes — they enumerate inputs, outputs, safety rules, and prices without auth:

Unauthenticated schema endpoints
MethodPathModeDescription
GET/api/bankrbot/schemaliveAutonomy-path routes, modes, mandatory fuses, LiveAutonomyAck shape, x402 call plan.
GET/api/vaults/schemaliveVault routes, chain/payment model, fee schedule, public deposit gate.
GET/api/x402/schemalivePayment lanes per service: provider, payment chain, price, settlement asset.
GET/api/vaults/asset-registryliveSource-verified Robinhood Chain tokenized assets with oracle and jurisdiction policies.
curl
curl -s https://app.hiss.finance/api/vaults/schema