Agent tools API

Overview

The tools API is the HTTP face of CoilOps: thin, validated wrappers over the same @hiss/core functions the MCP server exposes. Shipping this pass. All routes are POST with JSON bodies, need no authentication, and answer free in the current public build. Every request may include an optional nowIso (ISO-8601) to pin the clock for deterministic, replayable output.

Routes

Machine-readable agent index

GET /api/agents/schema is the deterministic index of the agent-facing Bankr workflows — Bankrbot vault deposits, Bankr stock-token trades, the vault rebalance paths, provider rewards, and the rh-wallet boundary. Each workflow entry carries its endpoints, env-gate names (never values), truth rules, MCP tool names, skill pack, and its rail id from the @hiss/core rail-boundaries model (rail_a_vault_deposit · rail_b_bankr_stock_token · rail_c_rh_wallet_external). Sibling schema routes: /api/bankrbot/schema, /api/vaults/schema, /api/x402/schema.

MCP tool index

The local stdio MCP server exposes 34 tools over the same @hiss/core functions. CoilOps: hiss_generate_coil, hiss_validate_coil, hiss_score_coil, hiss_create_receipt, hiss_compile_robinhood_capsule, hiss_risk_audit, hiss_drift_check, hiss_export_share_card, hiss_verify_receipt, hiss_explain_oracle_policy. Autonomy path: hiss_compile_bankrbot_robinhood_path, hiss_validate_autonomy_fuses, hiss_generate_bankrbot_command_pack, hiss_generate_robinhood_mcp_instructions, hiss_post_run_audit. Vaults: hiss_validate_usdg_vault, hiss_create_vault_manifest, hiss_compile_vault_rebalance_policy, hiss_generate_vault_deposit_intent, hiss_generate_vault_receipt, hiss_post_vault_rebalance_audit, hiss_calculate_vault_fees, hiss_score_vault_risk, hiss_compare_vaults_without_recommendation.

Bankr rails (Rail A deposits, Rail B stock tokens, rebalances, rewards): hiss_prepare_bankrbot_vault_deposit, hiss_generate_bankrbot_deposit_command, hiss_reconcile_bankrbot_deposit_receipt (see Bankrbot vault deposits), hiss_prepare_bankr_stock_token_trade, hiss_generate_bankr_stock_token_command, hiss_submit_bankr_stock_token_intent (gated — refuses unless BANKR_AGENT_API_ENABLED and BANKR_API_KEY are configured, and even then the local server never transmits), hiss_reconcile_bankr_stock_token_job (see the Bankr stock-token lane), hiss_prepare_vault_bankr_rebalance, hiss_import_bankr_fee_claim, hiss_plan_provider_rewards (see provider rewards). Every tool rejects credential-looking fields and passes the execution-claim output guard; none holds a secret or transmits anything. The rh-wallet boundary has deliberately no tools — it is a boundary statement, not a workflow.

Response envelope

Every success is a flat JSON object with the tool name, timestamp, tool-specific fields, and two invariants that are always present:

{
  "tool": "validate-coil",
  "generatedAt": "2026-07-07T00:00:00.000Z",
  "validation": { "valid": true, "issues": [] },
  "receipt": { "receiptId": "hrcpt_…", "…": "…" },
  "notInvestmentAdvice": true,
  "liveOrderSent": false
}

Error shape

{
  "error": {
    "code": "COIL_SHAPE",             // stable, machine-readable
    "message": "`coil` is not a structurally valid CoilManifest.",
    "issues": [
      { "code": "COIL_EXECUTION_MODE", "message": "coil.executionMode must be one of …" }
    ]
  }
}

Rate limits

• 30 requests per 5 minutes, per client, per tool. Exceeding it returns 429 with a retry-after header (seconds).
• Request bodies are capped at 256 KB.

Examples

curl -s https://app.hiss.finance/api/tools/generate-coil \
  -H "content-type: application/json" \
  -d '{"prompt": "AI infra without full NVDA concentration"}'

const res = await fetch("https://app.hiss.finance/api/tools/generate-coil", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ prompt: "AI infra without full NVDA concentration" }),
});
if (!res.ok) throw new Error(`generate-coil failed: ${res.status}`);
const { coil, health, receipt } = await res.json();

curl -s https://app.hiss.finance/api/tools/validate-coil \
  -H "content-type: application/json" \
  -d '{"coil": { …CoilManifest… }}'

const res = await fetch("https://app.hiss.finance/api/tools/compile-capsule", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    coil, // a non-paper CoilManifest
    options: { maxTotalNotionalUsd: 1000 },
    // agentic_mcp_enabled additionally needs
    // options.userAcknowledgedAgenticMode: true
  }),
});
const { capsule, receipt } = await res.json();

curl -s https://app.hiss.finance/api/tools/drift-check \
  -H "content-type: application/json" \
  -d '{"coil": { … }, "currentWeightsBps": {"AMD": 3200, "MU": 2400}}'

const res = await fetch("https://app.hiss.finance/api/coil/verify", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ coil, receipt }),
});
const { verification } = await res.json();
// verification: { ok: boolean, mismatches: string[] }