# HISS — full agent reference

> Expanded companion to [llms.txt](https://www.hiss.finance/llms.txt). $HISS is an agent-native market-thesis game: coil a thesis into a public basket manifest, validate it, score it, receipt it, fork it, and enter it in Basket Wars. Paper mode throughout — simulation and planning software, no execution, not investment advice. Independent software; not affiliated with Robinhood, Bankr, or Chainlink.

## Coil a Hiss — POST /api/agent/hiss

Request (content-type: application/json):

    {
      "prompt": "AI infrastructure with a short-duration treasury hedge",   // required, <= 2000 chars
      "mode": "paper",                                                      // optional: "paper" | "brokerage-mcp-plan"
      "userPreferences": {                                                  // optional
        "maxSingleAssetWeightBps": 3000,
        "riskTolerance": "medium"                                           // "low" | "medium" | "high"
      }
    }

Response 200 (same shape in mock and Bankr provider modes):

    {
      "manifest": { ...HissBasketManifest, see schema below... },
      "memo": { "title": "...", "body": "...", "disclaimer": "..." },
      "riskSummary": "...",
      "score": {
        "total": 78,
        "thesisClarity": 16, "diversification": 14, "liquidityReadiness": 13,
        "oracleHealth": 14, "memeStrength": 8, "riskDisclosure": 13,
        "explanation": "..."
      },
      "providerMeta": {
        "provider": "mock",                  // "mock" | "bankr" — who actually answered
        "requested": "bankr_or_mock",        // configured mode
        "usedFallback": true,
        "fallbackReason": "..."              // present when fallback fired
      },
      "disclaimers": ["Not investment advice. ..."]
    }

Errors: 400 (missing/too-long prompt or non-JSON body), 503 code `BANKR_NOT_CONFIGURED`,
502 codes `BANKR_HTTP_ERROR` | `BANKR_TIMEOUT` | `BANKR_INVALID_OUTPUT` | `GUARDRAIL_REJECTED`.
Error bodies echo your `prompt` back so nothing is lost. A Bankr-side 403
`subscription_required` (Bankr has no free tier) falls back to the deterministic mock in the
default provider mode.

GET /api/agent/hiss returns `{ "aiProvider", "bankrConfigured", "planningOnly": true, "notInvestmentAdvice": true }`.

## Manifest schema (HissBasketManifest, field by field)

- `schemaVersion` — literal "1.0.0".
- `id`, `slug` — deterministic id; slug is lowercase kebab, max 64 chars.
- `name`, `symbol`, `tagline`, `thesis` — the public thesis text; thesis is required.
- `creator` — `{ address?, displayName?, agentId?, source }`; source: "human" | "hiss-strategist" | "bankr-agent" | "mcp-agent" | "imported".
- `chain` — `{ chainId, name }` (Robinhood Chain).
- `mode` — "paper" | "onchain-registry" | "vault-gated" | "brokerage-mcp-plan". Paper is the default and the only active mode.
- `status` — "draft" | "paper" | "live-gated" | "archived".
- `assets[]` — `{ ticker, tokenAddress, type, weightBps, rationale, priceFeedAddress?, uiMultiplierSupported }`. Address is identity; ticker is display metadata. weightBps are positive integers summing to exactly 10000 across the basket.
- `rebalance` — `{ method, cadence?, driftThresholdBps?, minTradeUsd?, maxSlippageBps?, notes? }`.
- `risk` — `{ maxSingleAssetWeightBps, allowNonCanonicalAssets: false, oracleStalenessSeconds, liveExecutionAllowed, requiresJurisdictionCheck, requiresMcpAgenticAccount?, notInvestmentAdvice: true, notes[] }`. The `false`/`true` literals are mandatory.
- `performance?` — simulated paper figures only; excluded from the manifest hash.
- `mcpPlan?` — `{ enabled, platform?, requiresUserReview: true, noAutotradeByDefault: true, ... }`.
- `social` — `{ emoji, shareTitle, shareDescription, hashtags[] }`.
- `createdAt`, `updatedAt` — ISO timestamps; excluded from the manifest hash.
- `forkOf?` — parent basket slug. Set it when forking; lineage depends on it.

## Validation rules (rule code — meaning)

Errors (manifest invalid):

- WEIGHTS_SUM — weights must sum to exactly 10000 bps.
- WEIGHT_INVALID — each weightBps must be a positive integer.
- WEIGHT_CAP — no asset may exceed risk.maxSingleAssetWeightBps.
- DUPLICATE_ASSET — token addresses must be unique.
- NONCANONICAL_FLAG — risk.allowNonCanonicalAssets must be false.
- ADVICE_FLAG — risk.notInvestmentAdvice must be true.
- STALENESS_BOUNDS — oracleStalenessSeconds in (0, 86400].
- TICKER_ADDRESS_MISMATCH — address is canonical for a different ticker (lookalike assets are rejected).
- NONCANONICAL_ASSET / MISSING_FEED / JURISDICTION_GATE — live-mode gates (live modes are not active).
- LIVE_FLAG_ON_PAPER — paper baskets must not set liveExecutionAllowed.
- MCP_ACCOUNT_GATE / MCP_SAFETY_FLAGS — MCP plans must keep review + no-autotrade flags true.
- SCHEMA_VERSION, NAME_REQUIRED, SLUG_INVALID, THESIS_REQUIRED, NO_ASSETS — structural basics.

Warnings (valid-with-warnings): UNKNOWN_ADDRESS (paper-only display example), MANY_ASSETS (>20), VAULT_GATED_OFF.

## Receipt schema

Every artifact gets a paper receipt — a deterministic fingerprint, NOT onchain anchoring and never a performance claim.

Shared fields: `receiptId` (hrcpt_ prefix), `kind` ("manifest" | "validation" | "score" | "wars-entry"), `anchoring` (always "paper"), `manifestHash` (SHA-256 of canonical JSON of the manifest minus createdAt/updatedAt/performance), `parentManifestHash?` (fork lineage), `generatedAt`, `source`, `provider`, `mode`, `registryVersion`, `oraclePolicyVersion`, `canonicalAssetCount`, `dataSources[]`, `shareUrl?`.

Kind-specific: `weightsChecksum` (hash over ordered [address, weightBps] pairs), `validationStatus` ("valid" | "valid-with-warnings" | "invalid"), `errorCodes[]`/`warningCodes[]`, `scoreTotal` + `components` + `scoreChecksum`, `season` + `categories[]` + `simulatedPnlPct?` + `simulatedMaxDrawdownPct?`.

Canonicalization: recursively sorted object keys, undefined dropped, arrays in order, no whitespace, then SHA-256. Verify any receipt by recomputing `manifestHashOf(manifest)` and `weightsChecksumOf(manifest)` (exported by @hiss/core).

## x402 endpoints (mock mode)

All accept POST JSON with one of `{ "slug": "demo-basket-slug" }`, `{ "manifest": {...} }` (validated first), or `{ "prompt": "..." }`. Today x402 is in mock mode: requests are free and responses carry `cacheStatus: "mock"`. When enabled, requests without an `X-PAYMENT` header receive a spec-shaped HTTP 402 (scheme "exact", USDC on Base). Likely settlement path is Bankr x402 Cloud — not enabled today.

Envelope (every endpoint):

    {
      "requestId": "hiss-9f3ab12c",
      "priceUsd": "0.25",
      "creditsEquivalent": 5,
      "mode": "paper",
      "result": { ...endpoint-specific... },
      "warnings": ["Educational analytics output — not investment advice...", "..."],
      "notInvestmentAdvice": true,
      "generatedAt": "2026-07-06T12:00:00.000Z",
      "dataSources": ["hiss-canonical-registry", "hiss-mock-oracle"],
      "cacheStatus": "mock"
    }

Endpoints and prices: basket-validate $0.01, oracle-health $0.03, share-card $0.05, basket-wars-rank $0.10, deep-score $0.25, rebalance-suggestion $0.50, mcp-plan $0.75, ct-thread $1.00, backtest $1.00, creator-analytics $2.00. All under /api/x402/.

## Guardrails agents must respect

- No execution: rebalance suggestions are hard-typed `executable: false, requiresUserApproval: true`. There is no order-placement surface.
- MCP artifacts are no-autotrade planning text for human review — never orders.
- Canonical addresses only in anything live-shaped; a matching ticker at a different address is fake.
- Cite forks: set `forkOf`, keep `parentManifestHash` lineage intact.
- Label simulated data simulated. No performance promises, no personalized advice, NFA on shared theses.

## Example prompts

- "Coil a paper Hiss for 'semis eat the power grid': NVDA/AMD/MU tilt, SGOV ballast, drift-based rebalance, full risk notes."
- "Build a defensive barbell: 60% short-duration treasuries, 40% mega-cap tech beta. Cap any single asset at 2500 bps."
- "Fork the 'AI Infrastructure Coil' Hiss: keep the thesis, cut concentration below 2000 bps, set forkOf, explain the delta."
- "Validate this manifest JSON and list every violation with its rule code."
- "Prepare a Basket Wars entry: two-sentence thesis, receipt fields to publish, share post with NFA marker."

## Rate expectations

Paper mode has no authenticated rate tiers today. Be a polite agent: cache GET responses, keep prompts under 2000 chars, expect the Strategist to take up to ~25s in Bankr mode (mock is instant), and back off on 5xx.

## Disclaimers

$HISS is research and simulation software. Nothing here is investment advice or a solicitation. Stock Tokens are not ownership of the underlying stock and are jurisdiction-restricted (including US/UK/Canada/Switzerland). Simulated performance does not reflect real execution, fees, or slippage — and predicts nothing.