HTTP 402 Payment Required

Pay for API calls
with Bitcoin SV

No accounts. No subscriptions. Send a request, pay in satoshis, get your response. OpenAI-compatible endpoints backed by Grok.

API ReferenceHow it works
BSV API

Protocol

BSVAPI uses HTTP 402 for payment negotiation. The flow is three requests, or two if you already know the price.

Step 1

Request

Send your request without payment. The server responds with 402 and the price in satoshis.

POST /api/v1/chat/completions
Content-Type: application/json

{"model":"grok-3-mini","messages":[{"role":"user","content":"Hello"}]}

← 402 Payment Required
← x-bsv-payment-satoshis-required: 500

Step 2

Pay

Create a BSV transaction for the required amount. Include the txid in the x-bsv-payment header.

POST /api/v1/chat/completions
Content-Type: application/json
x-bsv-payment: a1b2c3d4e5f6...

{"model":"grok-3-mini","messages":[{"role":"user","content":"Hello"}]}

Step 3

Receive

Payment is verified on-chain. The request is proxied upstream. You get the response with a payment receipt.

← 200 OK

{
  "choices": [{
    "message": {"role":"assistant","content":"Hello! How can I..."}
  }],
  "usage": {"prompt_tokens":12,"completion_tokens":84},
  "payment": {"txid":"a1b2c3...","satoshisPaid":500}
}

Implements BRC-0105 HTTP Service Monetization. Compatible with PacketPay clients for automatic payment handling.

For businesses

Registered clients get an API key, metered usage, and volume discounts. Calls are invoiced monthly in BSV.

POST /api/v1/chat/completions
Authorization: Bearer bsvapi_sk_yourcompany_xxx
Content-Type: application/json

{"model":"grok-3","messages":[{"role":"user","content":"..."}]}

← 200 OK  (no payment header needed — metered to your account)
TierDiscountBilling
Internal50%Monthly BSV invoice
Partner25%Monthly BSV invoice
External0%Monthly BSV invoice

Pricing

2x upstream cost. Paid in BSV at the current exchange rate.

ModelInputOutput
grok-3$6.00 / 1M$30.00 / 1M
grok-3-mini$0.60 / 1M$1.00 / 1M
grok-2$4.00 / 1M$20.00 / 1M

Use POST /api/v1/price to get the exact cost in satoshis before calling.

Reference

GET/api/v1/models

List available models. No authentication required.

curl https://bsvapi.com/api/v1/models
POST/api/v1/price

Get a price estimate in satoshis. No authentication required.

curl -X POST https://bsvapi.com/api/v1/price \
  -H "Content-Type: application/json" \
  -d '{"model":"grok-3-mini","messages":[{"role":"user","content":"Hello"}]}'
POST/api/v1/chat/completions

OpenAI-compatible chat completions. Requires BSV payment or API key.

# Anonymous (BSV payment)
curl -X POST https://bsvapi.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "x-bsv-payment: <txid>" \
  -d '{"model":"grok-3-mini","messages":[{"role":"user","content":"Hello"}]}'

# Registered client (API key)
curl -X POST https://bsvapi.com/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer bsvapi_sk_yourcompany_xxx" \
  -d '{"model":"grok-3-mini","messages":[{"role":"user","content":"Hello"}]}'