inference-mcp

List the models this BSV inference gateway sells, with LIVE retail price (satoshis per 1,000 tokens) at the current BSV/USD rate. No key needed. Call first to choose a model.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Run one metered inference (OpenAI-compatible), paid per token in Bitcoin BSV from your prepaid channel. Returns the completion plus a receipt: satoshis charged, model routed to, remaining balance, and the broker-signed usage receipt. Needs a funded channel key: send the HTTP header "Authorization: Bearer channelId:channelSecret" with the MCP request, or pass apiKey. Thinking models (claude-sonnet-5, claude-opus-5, claude-opus-5-5, claude-fable-5-1) bill their hidden reasoning as output, and maxTokens is raised to at least 1024 for them. On failure the tool returns isError with text "error: <code> (<http status>): <message>". Codes: no_channel_key (no Authorization header and no apiKey); invalid_channel (401: channel not found, bad secret, or closed; open a new one); insufficient_balance (402: the channel cannot cover the worst case for this call; the text includes requiredSats and balanceSats; top up at the website, or lower maxTokens / turn off webSearch); invalid_request (400: unknown model or policy, a model whose provider is not enabled, or a malformed prompt; call list_models); upstream_failed (502: the model provider failed; nothing is charged, retry or pick another model). Nothing is charged on any error. This server does not verify its own receipt: check usageReceipt offline with @bsvkey/x402-bsv-client (verifyReceipt, verifyCharge, verifyMeter) against the key at /v1/receipt-key.

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "The user prompt."
    },
    "model": {
      "type": "string",
      "description": "Model id or policy: auto|cheapest|best, claude-*, grok-*.",
      "default": "auto"
    },
    "system": {
      "type": "string",
      "description": "Optional system prompt."
    },
    "maxTokens": {
      "type": "integer",
      "description": "Max output tokens.",
      "default": 512
    },
    "webSearch": {
      "type": "boolean",
      "description": "Let the model search the live web (adds a per-search fee).",
      "default": false
    },
    "apiKey": {
      "type": "string",
      "description": "channelId:channelSecret for a funded channel. Omit to use the Authorization header (preferred)."
    }
  },
  "required": [
    "prompt"
  ],
  "additionalProperties": false
}

Check a prepaid channel’s remaining Bitcoin BSV balance, spend, and request count. Uses the Authorization header or apiKey. On failure returns isError "error: <code> (<status>): <message>": no_channel_key, or invalid_channel (401/404: not found, bad secret, or closed).

{
  "type": "object",
  "properties": {
    "apiKey": {
      "type": "string",
      "description": "channelId:channelSecret. Omit to use the Authorization header (preferred)."
    }
  },
  "additionalProperties": false
}

Explains how to open + fund a prepaid channel. Funding is a real Bitcoin BSV payment signed by a wallet, so it is done once at the website; you then send the returned channel key as "Authorization: Bearer channelId:channelSecret" (or pass it as apiKey).

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Run one inference paid PER CALL in Bitcoin BSV via x402, no prepaid channel. Non-custodial, two steps: (1) call without payment to get the 402 quote (status payment_required, accepts[]); nothing is spent. (2) Build and sign a BSV payment for that quote in your own wallet (for example fetchWithX402 / buildPayment in @bsvkey/x402-bsv-client) and call again with the same prompt, model, maxTokens and webSearch plus payment = the base64 X-PAYMENT value. Returns the completion plus the on-chain settlement txid. This server never takes a private key: a wif argument is refused. On failure returns isError "error: <code> (<status>): <message>". Codes: key_refused (a private key was sent; it was not used or forwarded); payment_failed (402: the payment did not settle; nothing is spent); invalid_request (400: unknown model or bad input; nothing is spent); upstream_failed (502: the payment SETTLED but the model provider then failed; the text includes the settlement txid. There is no automatic refund: contact [email protected] with that txid).

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "The user prompt."
    },
    "model": {
      "type": "string",
      "description": "Model id or policy: auto|cheapest|best, claude-*, grok-*.",
      "default": "grok-4.3"
    },
    "system": {
      "type": "string",
      "description": "Optional system prompt."
    },
    "maxTokens": {
      "type": "integer",
      "description": "Max output tokens.",
      "default": 512
    },
    "webSearch": {
      "type": "boolean",
      "description": "Let the model search the live web (adds a per-search fee to the quote).",
      "default": false
    },
    "payment": {
      "type": "string",
      "description": "The base64 X-PAYMENT header value your wallet signed for the quote from step 1. Omit to get the quote."
    }
  },
  "required": [
    "prompt"
  ],
  "additionalProperties": false
}

Run one inference paid PER CALL in XRP on the XRP Ledger via x402, no channel. Non-custodial, two steps: (1) call without payment to get the 402 quote (exact drops, destination, destination tag, signed quote; priced from the XRP Ledger's own XRP/RLUSD market); nothing is spent. (2) Sign one XRP Payment for exactly that in your own wallet and call again with the same prompt, model and maxTokens plus payment = base64 of {"x402Version":1,"scheme":"exact","network":<from quote>,"payload":{"txBlob":<signed blob>,"quote":<accepts[0].extra.quote>}}. The broker checks the payment before broadcasting it, waits for validation (a few seconds), and returns the completion, the settlement tx hash, and a signed receipt. This server never takes a wallet seed: an xrpSeed argument is refused. On failure returns isError "error: <code> (<status>): <message>". Codes: key_refused; pending (202: submitted but not validated yet; call again with the same payment); payment_failed (402: the payment was refused before broadcast or did not settle; nothing is spent unless the text includes a settlement tx); invalid_request (400); upstream_failed (502: the payment SETTLED but the model provider then failed; the text includes the settlement tx. No automatic refund: contact [email protected] with it).

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "The user prompt."
    },
    "model": {
      "type": "string",
      "description": "Model id or policy: auto|cheapest|best, claude-*, grok-*.",
      "default": "claude-haiku-4-5"
    },
    "system": {
      "type": "string",
      "description": "Optional system prompt."
    },
    "maxTokens": {
      "type": "integer",
      "description": "Max output tokens.",
      "default": 512
    },
    "payment": {
      "type": "string",
      "description": "The base64 X-PAYMENT value carrying your signed XRP Payment for the quote from step 1. Omit to get the quote."
    }
  },
  "required": [
    "prompt"
  ],
  "additionalProperties": false
}