Skip to content

Agent tools API

developerpaper mode

The /api/tools/* and /api/coil/* reference: request/response, examples, rate limits, error shapes.

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

MethodPathModeDescription
POST/api/tools/generate-coilmock{ prompt, executionMode? } → { coil, health, receipt, providerMeta, disclaimers }. Strategist (mock or Bankr) → Coil.
POST/api/tools/validate-coillive{ coil } → { validation: { valid, issues[] }, receipt }. A verdict — invalid Coils return 200 with issues, never a throw.
POST/api/tools/score-coillive{ coil } → { health, receipt }. Coil Health 0–100 (structure/readiness, never returns).
POST/api/tools/compile-capsulelive{ coil, options? } → { capsule, receipt }. Non-paper Coils only; agentic mode needs options.userAcknowledgedAgenticMode: true.
POST/api/tools/risk-auditlive{ coil } → { fuses[], requiredForCapsule, missingRequired, issues, fuseChecksum, receipt }.
POST/api/tools/drift-checklive{ coil, currentWeightsBps? } → { report, receipt }. Proposals are previews requiring human confirmation.
POST/api/tools/receiptlive{ coil, kind? } → { receipt }. Kinds: coil_manifest (default), validation, risk_fuse.
POST/api/tools/share-cardlive{ coil, shareUrlBase? } → { card, receipt }. A thesis artifact, never a performance claim.
POST/api/coil/verifylive{ coil, receipt } → { verification: { ok, mismatches[] } }. Recomputes every load-bearing hash.

Response envelope

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

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

Error shape

error statuses
FieldTypeRequiredDescription
400BODY_* / COIL_SHAPE / PROMPT_REQUIRED / …noMalformed JSON, wrong shapes, bad parameters. issues[] carries field-level details.
413BODY_TOO_LARGEnoJSON body over 256 KB.
422COIL_INVALID / CAPSULE_COMPILEnoStructurally fine but semantically invalid — validation errors or capsule-compile failures (incl. AGENTIC_ACK_REQUIRED).
429RATE_LIMITEDnoRate limit exceeded; retry-after header set.
500OUTPUT_GUARDnoResponse blocked by the execution-claim scanner.
error envelope
{
  "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

generate a coil (curl)
curl -s https://www.hiss.finance/api/tools/generate-coil \
  -H "content-type: application/json" \
  -d '{"prompt": "AI infra without full NVDA concentration"}'
generate a coil (fetch)
const res = await fetch("https://www.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();
validate (curl)
curl -s https://www.hiss.finance/api/tools/validate-coil \
  -H "content-type: application/json" \
  -d '{"coil": { …CoilManifest… }}'
compile a capsule (fetch)
const res = await fetch("https://www.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();
drift check (curl)
curl -s https://www.hiss.finance/api/tools/drift-check \
  -H "content-type: application/json" \
  -d '{"coil": { … }, "currentWeightsBps": {"AMD": 3200, "MU": 2400}}'
verify a receipt (fetch)
const res = await fetch("https://www.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[] }

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