x402 payments

developerpaper mode

Pay-per-request over HTTP 402: flow, endpoint prices, and current mock mode.

The idea, simply

x402 revives HTTP status code 402 ("Payment Required") as a machine-payment protocol: an agent calls an API, gets a 402 that says exactly what to pay and where, pays in stablecoins, retries with a payment header, and gets the result. No accounts, no API keys, no invoices — per-request payments that AI agents can complete autonomously.

Current public mode: disabled

x402 payment enforcement is off in the public build (NEXT_PUBLIC_ENABLE_X402 unset). All ten endpoints answer for free with the standard envelope labeled cacheStatus: "mock", so agents can integrate against real shapes today without spending anything.

today (mock mode)

curl -s https://www.hiss.finance/api/x402/oracle-health \
  -H "content-type: application/json" \
  -d '{"prompt": "Mag 7 momentum with lower drawdown"}'
# → 200 with a full envelope, cacheStatus: "mock", no payment involved

The 402 flow (when enabled)

The agent POSTs to a paid endpoint with no payment attached.
The server replies 402 with an accepts[] body: scheme, network, the exact amount in atomic USDC units, the resource path, and the payTo address.
The agent constructs the payment and retries the same request with an X-PAYMENT header carrying the signed payload.
The server verifies settlement and returns the result envelope.

402 response body

HTTP/1.1 402 Payment Required
content-type: application/json

{
  "x402Version": 1,
  "error": "X-PAYMENT header is required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "250000",
      "resource": "/api/x402/deep-score",
      "description": "Deep HISS Score with risk report, oracle health, and rebalance notes.",
      "mimeType": "application/json",
      "payTo": "0x…",
      "maxTimeoutSeconds": 60,
      "asset": "USDC"
    }
  ]
}

retry with payment

curl -s https://www.hiss.finance/api/x402/deep-score \
  -H "content-type: application/json" \
  -H "X-PAYMENT: <base64 payment payload per the x402 spec>" \
  -d '{"slug": "some-demo-basket"}'

Endpoints and prices

Rendered live from the X402_ENDPOINTS config in @hiss/core. Request bodies accept one of manifest, slug, or prompt — see the API reference for the shared envelope and examples.

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.

Verified settlement: not yet enabled

There is a third mode between "disabled" and "production": x402 enforcement can be switched on without settlement verification, in which case requests carrying any X-PAYMENT header are accepted unverified. That mode exists for integration testing only. Production payment requires Bankr facilitator settlement verification plus replay protection — neither is enabled yet, and the endpoints stay in mock mode until they are.

Errors

402 — payment required (enabled mode, no/invalid X-PAYMENT header).
400 — malformed body, or none of manifest/slug/prompt provided.
404 — unknown demo basket slug.
422 — inline manifest failed validation (details included).

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