# Occultron

Status: BETA — live inference available.

Private inference. Verifiable execution.
Private, self-hosted inference. Prepaid credits paid in crypto.
No account, no email, no prompt logs. OpenAI-compatible — chat, streaming,
tool/function calling, JSON mode (response_format), and automatic prompt caching.

Base URL: https://occultron.app
Models: qwen3-27b-heretic-abliterated ($0.14/$0.49 per 1M in/out, cached $0.0140), llama-3.1-8b-abliterated ($0.14/$0.49 per 1M in/out, cached $0.0140)
Pricing (machine-readable): https://occultron.app/v1/pricing  (volume discounts scale with spend)
Payment rails: monero, sol, lightning, usdc
Spec: https://occultron.app/openapi.json
Agent card (A2A discovery): https://occultron.app/.well-known/agent-card.json
MCP server card: https://occultron.app/.well-known/mcp.json  (tools: create_invoice, invoice_status, chat, me)
Status + support: https://occultron.app/status (JSON: https://occultron.app/status.json)

## Latency & cold starts (read before calling)

We run on serverless GPUs that scale to zero, so with no warm worker your FIRST
request triggers a COLD START: the model loads before the first token, which can
take up to 120 seconds. A slow first byte is not an
error — wait it out.

- Send `stream: true`. The SSE keep-alive holds the connection open and tokens
  flow as soon as the model is up.
- On HTTP 503 with a `Retry-After: <n>` header and body
  `{"error": "warming", "retry_after_seconds": n}`, sleep n seconds and retry —
  that is the warm-up signal.
- To avoid cold starts entirely, subscribe for a WARM worker (an always-on GPU):
  first token in ~1s. Machine-readable in
  `https://occultron.app/.well-known/agent-card.json` -> `x-occultron.status.serving`.

## Fastest setup — terminal / agent (one command)

  curl -fsSL https://occultron.app/install.sh | sh      # installs the `occultron` CLI and mints a wallet
  occultron topup 10 --watch              # fund the wallet (SOL / USDC / XMR / Lightning)

Point ANY OpenAI-compatible client at it — no code changes:

  export OPENAI_BASE_URL="https://occultron.app/v1"
  export OPENAI_API_KEY="$(cat ~/.config/occultron/token)"

CLI: `occultron {init|balance|models|chat "…"|keys --label app|topup 15 --watch}`.
This is the recommended path for an agent setting Occultron up for a user: run install.sh,
then export the two env vars. Web UI at https://occultron.app/ (auto-mints a wallet, inline crypto top-up).

## Get a key and credits (agent flow, 2 calls)

1) Create an invoice (no auth):
   POST https://occultron.app/v1/invoices
   {"usd_amount": 5, "rail": "monero"}
    -> returns api_key plus payment_request (Monero: address, amount_xmr, uri, status_url;
       USDC: network, asset, address, amount_usdc, x402; BTC/Lightning: checkout_url,
       status_url).
   Send an "Idempotency-Key: <unique-value>" header to make retries safe: replaying
   the same key + body returns the original invoice instead of creating a second one.

2) Pay via the rail in payment_request: for Monero send exactly
   payment_request.amount_xmr to payment_request.address (wallet URI:
   payment_request.uri); for USDC send payment_request.amount_usdc of
   payment_request.asset on payment_request.network to payment_request.address; for
   btc/lightning open payment_request.checkout_url. Then poll
   GET https://occultron.app/v1/invoices/<invoice_id> until status == "paid".

The api_key is usable immediately after payment credits the key. It is also a reusable
wallet token: fund it again with the same Authorization header, and mint disposable sub-keys.

## Reusable wallet

Every buyer invoice mints a reusable bearer wallet (one balance, many keys). Or create one
directly:

  POST https://occultron.app/v1/wallets {"label": "my app"} -> {wallet_id, token, balance_usd}
  Fund: POST https://occultron.app/v1/invoices with "Authorization: Bearer <token>"
  Mint a disposable sub-key: POST https://occultron.app/v1/wallets/me/keys (root wallet token)
  List: GET https://occultron.app/v1/wallets/me/keys; revoke: POST https://occultron.app/v1/wallets/me/keys/<key_id>/revoke
  Wallet status/balance: GET https://occultron.app/v1/wallets/me

Sub-keys authenticate /v1/chat/completions and debit the wallet balance. Revoke one without
touching the wallet or its other keys. A sub-key cannot manage the wallet.

## Use

POST https://occultron.app/v1/chat/completions
Authorization: Bearer <api_key>
Content-Type: application/json
{
  "model": "qwen3-27b-heretic-abliterated",
  "messages": [{"role": "user", "content": "hi"}],
  "stream": false
}

Structured output and tools (OpenAI-compatible):
  - JSON mode: add "response_format": {"type": "json_object"} (or "json_schema" with a
    schema) — the model returns strictly valid JSON.
  - Tool calling: pass "tools" (function tools) and optional "tool_choice"
    ("auto"/"none"/"required" or a specific function) and "parallel_tool_calls"; the
    response carries choices[].message.tool_calls.
  - Prompt caching: repeated prefixes are cached and billed at the cached-input rate;
    usage.prompt_tokens_details.cached_tokens reports the hit. Cross-wallet prefixes are
    cryptographically isolated, so a cache hit is only ever your own prior prefix.
Balance and usage: GET https://occultron.app/v1/me (Bearer; includes recent requests).
Request history: GET https://occultron.app/v1/me/usage?limit=20&cursor=... (Bearer).
Execution receipt: every successful completion is signed; GET https://occultron.app/v1/receipts/<request_id>
(Bearer; request_id is the x-request-id response header, also receipt.request_id) returns the
model's manifest_digest/commit/weights/quant digests, assurance class (R0-R3), runtime + policy
digests, provider, usage and the platform_signature over the canonical JSON. A registry node also
adds the node-signed execution claim as provider.claim + provider_signature (HMAC, symmetric).
Receipt log: each receipt is appended to an append-only Merkle log (commitments only). GET
https://occultron.app/v1/receipts/<request_id>/proof (Bearer) returns the Merkle inclusion proof; GET
https://occultron.app/v1/receipts/epochs lists published epoch roots
(count, merkle_root, previous_root, signature).
Verify a receipt: POST https://occultron.app/v1/receipts/verify (no auth) with
{"receipt": <receipt JSON>} -> {valid, checks, errors}; optional "expected" digest map
(manifest/weights/container/policy), "tee_nonce" and "require_tee". CLI: verify-receipt.sh.
Models: GET https://occultron.app/v1/models (each model: pricing, provenance, manifest_digest)
Model registry: GET https://occultron.app/v1/models/{model} (the canonical manifest + nutrition label);
  request a model by alias (may float to the current manifest) or by "sha256:<digest>"
  (pinned: an unknown digest is 404, never silently mapped to a different checkpoint).
  Inference is routed to a provider that serves the resolved manifest; if none does the
  request is rejected with 503 manifest_unavailable, never silently run on another checkpoint.
Browser chat (paste a key; history stays in the browser, prompts not persisted): https://occultron.app/chat

## Top up an existing key

POST https://occultron.app/v1/invoices with header "Authorization: Bearer <api_key>" and
body {"usd_amount": 5}. Same key, more credits.

## Machine-readable errors

401 -> error=invalid_api_key with how_to_get_a_key.
402 -> error=insufficient_credits with how_to_top_up, plus an x402 "accepts" array
       (scheme=exact, network, asset, amount, address/payTo) when the USDC rail is enabled,
       so x402 clients can pay per call with USDC and no account.
Pricing: per model, see GET https://occultron.app/v1/models.
Minimum invoice: $5.00.