API reference

developerpaper mode

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

Base URL and auth

All endpoints live under https://www.hiss.finance. In the current public build there is no authentication: everything runs in mock mode and answers for free. When x402 payments are enabled, the ten /api/x402/* endpoints will require payment per request (see x402 payments); the rest stay open. Every table below marks each endpoint's current mode.

Response envelope

Paid-tier analytics endpoints (all of /api/x402/*) share one envelope:

x402 response envelope fields
Field	Type	Required	Description
requestId	string	yes	Deterministic id for this request.
priceUsd	string	yes	Configured USD price of the endpoint.
creditsEquivalent	number	yes	Credit cost of the same action in-app.
mode	"paper" \| "onchain-readonly" \| "mcp-planning"	yes	Execution mode of the computation.
result	object	yes	The endpoint-specific payload.
warnings	string[]	yes	Standard research-only warnings plus endpoint-specific ones.
notInvestmentAdvice	true	yes	Always true. Machine-readable disclaimer.
generatedAt	string (ISO)	yes	Generation timestamp.
dataSources	string[]	yes	Data provenance, e.g. hiss-mock-oracle.
cacheStatus	"fresh" \| "cached" \| "mock"	yes	Always "mock" in the current public build.

example envelope

{
  "requestId": "hiss_9f2ab31c…",
  "priceUsd": "0.25",
  "creditsEquivalent": 5,
  "mode": "paper",
  "result": { "score": { "total": 71, "…": "…" }, "riskReport": "…" },
  "warnings": [
    "Educational analytics output — not investment advice and not a recommendation.",
    "Simulated/paper results do not reflect real execution, fees, or slippage.",
    "$HISS never executes trades; planning artifacts require explicit user review."
  ],
  "notInvestmentAdvice": true,
  "generatedAt": "2026-07-05T00:00:00.000Z",
  "dataSources": ["hiss-canonical-registry", "hiss-mock-oracle"],
  "cacheStatus": "mock"
}

Error envelope

errors

// Validation / input errors (400, 404, 422):
{ "error": "Manifest failed validation.", "details": [ { "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.

agent/hiss request fields
Field	Type	Required	Description
prompt	string	yes	The market whisper. Max 2000 characters.
mode	"paper" \| "brokerage-mcp-plan"	no	Planning mode. Defaults to paper.
basketContext	Partial<Manifest>	no	Existing basket to refine instead of starting fresh.
userPreferences	object	no	maxSingleAssetWeightBps and riskTolerance (low/medium/high).

agent/hiss response fields
Field	Type	Required	Description
manifest	HissBasketManifest	yes	The validated basket manifest.
memo	AgentMemo	yes	Title, markdown body, and disclaimer.
riskSummary	string	yes	Concentration and risk-intensity summary.
score	HissScore	yes	Composite plus per-component scores.
providerMeta	object	yes	provider, requested, usedFallback, fallbackReason, jobId, latencyMs.
disclaimers	string[]	yes	Research-only disclaimers.

curl

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

typescript

const res = await fetch("https://www.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);

response (abridged)

{
  "manifest": { "schemaVersion": "1.0.0", "name": "…", "assets": [ … ], "…": "…" },
  "memo": { "title": "…", "body": "…", "disclaimer": "…" },
  "riskSummary": "Largest position 25.0% …",
  "score": { "total": 74, "thesisClarity": 68, "…": "…" },
  "providerMeta": { "provider": "mock", "requested": "bankr_or_mock", "usedFallback": true },
  "disclaimers": ["Educational research tool. Not investment advice. …"]
}

GET /api/health

Service mode and feature-flag status. Safe metadata only — never secret values.

curl

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

response

{
  "ok": true,
  "service": "hiss-web",
  "mode": "paper",
  "aiProvider": "bankr_or_mock",
  "bankrConfigured": false,
  "x402": { "mode": "disabled", "note": "x402 endpoints serve free mock envelopes." },
  "flags": { "liveTrading": false, "vaultDeposits": false, "mcpMode": true, "mocks": true },
  "timestamp": "2026-07-05T00:00:00.000Z"
}

Baskets and share cards

Method	Path	Mode	Description
GET	/api/baskets	mock	List the deterministic demo baskets. Nothing persists server-side.
POST	/api/baskets	mock	Build a manifest from { input } or validate a full { manifest }; returns { manifest, validation }.
GET	/api/share-card?slug=…&plan=…	mock	SVG share card for a demo basket; free plans render a watermark.
GET/POST	/api/agent/hiss	mock	Strategist status (GET) and basket generation (POST), documented above.
GET	/api/health	live	Mode, provider, and flag status.

x402 endpoints

The ten machine-payable analytics endpoints. Prices and credit equivalents below render live from the X402_ENDPOINTS config in @hiss/core. All accept JSON bodies with one of manifest (inline, validated), slug (demo basket), or prompt (mock-generated). Today they answer free with cacheStatus: "mock"; the payment flow is specified in x402 payments.

Method	Path	Price	Credits	Mode	Description
POST	/api/x402/basket-validate	$0.01	1	mock	Validate a basket manifest against weight, identity, and mode rules.
POST	/api/x402/oracle-health	$0.03	3	mock	Oracle health report for a basket's assets.
POST	/api/x402/share-card	$0.05	2	mock	Premium share-card payload for a basket.
POST	/api/x402/deep-score	$0.25	5	mock	Deep HISS Score with risk report, oracle health, and rebalance notes.
POST	/api/x402/rebalance-suggestion	$0.50	5	mock	Non-executable rebalance suggestion for a basket.
POST	/api/x402/mcp-plan	$0.75	10	mock	MCP-safe rebalance plan + no-autotrade system prompt.
POST	/api/x402/ct-thread	$1.00	5	mock	Social thread draft for a basket, disclaimers included.
POST	/api/x402/backtest	$1.00	10	mock	Simulated paper backtest (deterministic; clearly labeled).
POST	/api/x402/creator-analytics	$2.00	10	mock	Creator-level fork/engagement analytics.
POST	/api/x402/basket-wars-rank	$0.10	5	mock	Basket Wars ranking breakdown for a basket.

curl

curl -s https://www.hiss.finance/api/x402/deep-score \
  -H "content-type: application/json" \
  -d '{"prompt": "Defensive cashflow basket"}'

typescript

const res = await fetch("https://www.hiss.finance/api/x402/deep-score", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ slug: "some-demo-basket" }), // or { prompt } or { manifest }
});
const envelope = await res.json();
// envelope.cacheStatus === "mock" in the current public build
console.log(envelope.requestId, envelope.result);

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