{
  "openapi": "3.1.0",
  "info": {
    "title": "BSVKey Inference",
    "version": "1.0.0",
    "summary": "OpenAI-compatible LLM inference, paid per call over x402 (USDC on Base or BSV). No account, no card. Every call returns a cryptographically signed, offline-verifiable usage receipt.",
    "description": "BSVKey Inference is an OpenAI-compatible inference gateway. Pay per request with the x402 payment standard: settle in USDC on Base via Coinbase's x402 facilitator, or in BSV micropayments. There is no signup, dashboard, or API key to manage. Models: Claude (Haiku 4.5, Sonnet 5, Opus 5, Fable 5.1) and xAI Grok, plus the aliases `auto`, `cheapest`, and `best`. Every response carries a signed usage receipt you can verify offline by recomputing the meter and recovering the signer against the key at GET /v1/receipt-key.\n\nTwo ways to pay:\n1. Pay-per-call (x402): POST to an /x402 endpoint with no payment to get a 402 with the payment requirements, build and attach the payment, and retry. USDC-on-Base uses x402 v2 (requirements in the `PAYMENT-REQUIRED` header, payment in `PAYMENT-SIGNATURE`); BSV uses x402 v1 (`X-PAYMENT` header).\n2. Prepaid channel: open a channel once, then call the OpenAI-compatible /chat/completions with `Authorization: Bearer <channelId>:<channelSecret>`.",
    "contact": { "name": "Embryo Space Inc. DBA BSVKey", "email": "embryospace@gmail.com", "url": "https://inference.bsvkey.com" },
    "license": { "name": "MIT" }
  },
  "servers": [{ "url": "https://inference.bsvkey.com/v1", "description": "Production" }],
  "tags": [
    { "name": "inference", "description": "OpenAI-compatible chat completions" },
    { "name": "x402", "description": "Pay-per-call payment endpoints and discovery" },
    { "name": "catalog", "description": "Models, live pricing, and the receipt-verification key" }
  ],
  "paths": {
    "/models": {
      "get": {
        "tags": ["catalog"],
        "summary": "List available models and live per-token pricing",
        "operationId": "listModels",
        "responses": {
          "200": {
            "description": "The model catalog.",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelList" } } }
          }
        }
      }
    },
    "/pricebook": {
      "get": {
        "tags": ["catalog"],
        "summary": "Live retail prices at the current BSV/USD rate",
        "operationId": "getPricebook",
        "responses": { "200": { "description": "Per-1k-token retail prices (sats and USD) plus the live BSV/USD rate.", "content": { "application/json": { "schema": { "type": "object" } } } } }
      }
    },
    "/receipt-key": {
      "get": {
        "tags": ["catalog"],
        "summary": "Pinned public key for verifying usage receipts offline",
        "operationId": "getReceiptKey",
        "responses": { "200": { "description": "The pinned key that signs every receipt, plus the receipt schemas it covers.", "content": { "application/json": { "schema": { "type": "object", "properties": { "receiptPubKey": { "type": "string", "example": "02b08e8821ff3e45d02a782bd07f4c4688aea49a836d5b3ca31e17d8f44fd03c1f" }, "schema": { "type": "string", "example": "bsvkey.usage-receipt/2" }, "envelope": { "type": "string", "example": "compact-bsm-secp256k1" }, "x402Receipt": { "type": "object", "description": "The per-call x402 delivered receipt schema (bsvkey.x402-receipt/1)." } } } } } } }
      }
    },
    "/x402/base/chat/completions": {
      "post": {
        "tags": ["x402", "inference"],
        "summary": "Pay-per-call inference, settled in USDC on Base (x402 v2)",
        "description": "Send with no payment to receive a 402 whose `PAYMENT-REQUIRED` response header carries the x402 v2 payment requirements (scheme `exact`, network `eip155:8453` Base, asset USDC). Build the payment, attach it in the `PAYMENT-SIGNATURE` header, and retry to receive the completion. The on-chain settlement is returned in the `PAYMENT-RESPONSE` header and in `x_usdc`. Minimum $0.01 per call. A GET to this path returns the same 402 envelope for discovery.",
        "operationId": "x402BaseChatCompletions",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } },
        "parameters": [{ "name": "PAYMENT-SIGNATURE", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded x402 v2 PaymentPayload. Omit to receive the 402 requirements first." }],
        "responses": {
          "200": { "description": "The completion. Settlement in the `PAYMENT-RESPONSE` header and `x_usdc`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } } } },
          "402": { "description": "Payment required. Requirements are in the `PAYMENT-REQUIRED` header (and echoed in the body).", "headers": { "PAYMENT-REQUIRED": { "schema": { "type": "string" }, "description": "Encoded x402 v2 PaymentRequired." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }
        }
      },
      "get": {
        "tags": ["x402"],
        "summary": "Discover the USDC-on-Base payment requirements",
        "operationId": "x402BaseDiscover",
        "responses": { "402": { "description": "The x402 v2 payment envelope for this resource.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } } }
      }
    },
    "/x402/chat/completions": {
      "post": {
        "tags": ["x402", "inference"],
        "summary": "Pay-per-call inference, settled in BSV (x402 v1)",
        "description": "Send with no payment to receive a 402 with the x402 v1 requirements (scheme `bsv-p2pkh`). Build a BSV payment, attach it in the `X-PAYMENT` header, and retry. The on-chain settlement txid is returned in `X-PAYMENT-RESPONSE`. Sub-cent per call. The npm client `@bsvkey/x402-bsv-client` handles the whole handshake. A GET to this path returns the same 402 for discovery. The paid 200 also carries a signed delivered receipt (`receipt`, schema `bsvkey.x402-receipt/1`): check it with `verifyX402ReceiptFull` against the key from /receipt-key and your own settlement txid, or paste it into https://inference.bsvkey.com/verify.html.",
        "operationId": "x402ChatCompletions",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } },
        "parameters": [{ "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded x402 v1 PaymentPayload. Omit to receive the 402 requirements first." }],
        "responses": {
          "200": { "description": "The completion. On-chain settlement txid in `X-PAYMENT-RESPONSE`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } } } },
          "402": { "description": "Payment required (x402 v1 envelope).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }
        }
      }
    },
    "/x402/testnet/chat/completions": {
      "post": {
        "tags": ["x402"],
        "summary": "Testnet sandbox: the pay-per-call handshake on BSV testnet (x402 v1)",
        "description": "The same handshake as /x402/chat/completions, paid with free BSV testnet coins (network `bsv-testnet`). The quote, the signed testnet payment, the broadcast and the signed delivered receipt are all real; the completion is a sandbox reply (model `sandbox:<model>`), not a model call. Drop `/testnet` from the path to go live. A GET returns the 402 for discovery.",
        "operationId": "x402TestnetChatCompletions",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } },
        "parameters": [{ "name": "X-PAYMENT", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Base64-encoded x402 v1 PaymentPayload paying on bsv-testnet. Omit to receive the 402 requirements first." }],
        "responses": {
          "200": { "description": "Sandbox completion. Testnet settlement txid in `X-PAYMENT-RESPONSE`; signed receipt in `receipt`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } } } },
          "402": { "description": "Payment required (x402 v1 envelope, network bsv-testnet).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequired" } } } }
        }
      }
    },
    "/chat/completions": {
      "post": {
        "tags": ["inference"],
        "summary": "OpenAI-compatible chat completions (prepaid channel)",
        "description": "Identical to the OpenAI chat completions API. Authenticate with a prepaid channel using `Authorization: Bearer <channelId>:<channelSecret>` (open one with POST /v1/channels). Supports `stream: true` (Server-Sent Events) and optional `web_search`.",
        "operationId": "chatCompletions",
        "security": [{ "ChannelBearer": [] }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletionRequest" } } } },
        "responses": {
          "200": { "description": "The completion (or an SSE stream when `stream` is true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChatCompletion" } } } },
          "401": { "description": "Missing or invalid channel credentials." },
          "402": { "description": "Insufficient channel balance." }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ChannelBearer": { "type": "http", "scheme": "bearer", "description": "Bearer token of the form `<channelId>:<channelSecret>` from POST /v1/channels." }
    },
    "schemas": {
      "Message": {
        "type": "object",
        "required": ["role", "content"],
        "properties": {
          "role": { "type": "string", "enum": ["system", "user", "assistant"] },
          "content": { "type": "string" }
        }
      },
      "ChatCompletionRequest": {
        "type": "object",
        "required": ["messages"],
        "properties": {
          "model": { "type": "string", "default": "auto", "description": "A model id or an alias (`auto`, `cheapest`, `best`).", "examples": ["auto", "claude-haiku-4-5", "claude-fable-5-1", "grok-4.3"] },
          "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" }, "minItems": 1 },
          "max_tokens": { "type": "integer", "default": 1024 },
          "stream": { "type": "boolean", "default": false, "description": "Only supported on the prepaid /chat/completions endpoint." },
          "web_search": { "type": "boolean", "default": false, "description": "Enable model web search (priced per search)." }
        }
      },
      "Usage": {
        "type": "object",
        "properties": {
          "prompt_tokens": { "type": "integer" },
          "completion_tokens": { "type": "integer" },
          "total_tokens": { "type": "integer" }
        }
      },
      "ChatCompletion": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "object": { "type": "string", "example": "chat.completion" },
          "created": { "type": "integer" },
          "model": { "type": "string" },
          "choices": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "index": { "type": "integer" },
                "message": { "$ref": "#/components/schemas/Message" },
                "finish_reason": { "type": "string", "example": "stop" }
              }
            }
          },
          "usage": { "$ref": "#/components/schemas/Usage" },
          "x_usdc": { "type": "object", "description": "USDC-on-Base settlement details (on the /x402/base endpoint).", "properties": { "paidAtomic": { "type": "integer" }, "priceUsd": { "type": "number" }, "asset": { "type": "string" }, "network": { "type": "string" }, "payTo": { "type": "string" }, "settlement": { "type": "string", "description": "On-chain transaction hash." } } },
          "x_bsv": { "type": "object", "description": "BSV settlement details (on the /x402 (BSV) endpoint)." },
          "receipt": { "type": "object", "description": "Signed delivered receipt (bsvkey.x402-receipt/1): binds the completion (outputDigest) to the settlement (settlementRef), signed by the key at /v1/receipt-key. Verify offline: recover the signer (compact BSM), recompute claimId, and check outputDigest == sha256(completion).", "properties": { "v": { "type": "string", "example": "bsvkey.x402-receipt/1" }, "rail": { "type": "string", "example": "base-usdc" }, "settlementRef": { "type": "string", "description": "On-chain settlement tx." }, "outputDigest": { "type": "string", "description": "sha256 of the completion bytes." }, "inputDigest": { "type": "string" }, "claimId": { "type": "string" }, "signature": { "type": "string" }, "brokerPubKey": { "type": "string" } } }
        }
      },
      "PaymentRequired": {
        "type": "object",
        "description": "x402 payment requirements returned with HTTP 402.",
        "properties": {
          "x402Version": { "type": "integer", "example": 2 },
          "error": { "type": "string", "example": "payment required" },
          "accepts": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "scheme": { "type": "string", "example": "exact" },
                "network": { "type": "string", "example": "eip155:8453" },
                "asset": { "type": "string", "example": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" },
                "amount": { "type": "string", "description": "Amount in atomic units (USDC has 6 decimals)." },
                "payTo": { "type": "string" },
                "maxTimeoutSeconds": { "type": "integer" },
                "extra": { "type": "object" }
              }
            }
          }
        }
      },
      "ModelList": {
        "type": "object",
        "properties": {
          "object": { "type": "string", "example": "list" },
          "data": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": { "type": "string" },
                "object": { "type": "string", "example": "model" },
                "provider": { "type": "string" }
              }
            }
          }
        }
      }
    }
  }
}