Payment Flow

Make a standard POST to any Solvela endpoint with no payment header. The body is a normal OpenAI-compatible chat completions payload.

curl -X POST https://api.solvela.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

The server will not forward this to any LLM. It responds immediately with HTTP 402.

The 402 body is the PaymentRequired object at the top level — not wrapped in the OpenAI { "error": { ... } } envelope. Parse the response body directly as JSON.

{
  "x402_version": 2,
  "resource": { "url": "/v1/chat/completions", "method": "POST" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "2625",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "pay_to": "<gateway-recipient-wallet>",
      "max_timeout_seconds": 300
    },
    {
      "scheme": "escrow",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "2625",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "pay_to": "<gateway-recipient-wallet>",
      "max_timeout_seconds": 300,
      "escrow_program_id": "9neDHouXgEgHZDde5SpmqqEZ9Uv35hFcjtFEPxomtHLU"
    }
  ],
  "cost_breakdown": {
    "provider_cost": "0.002500",
    "platform_fee": "0.000125",
    "total": "0.002625",
    "currency": "USDC",
    "fee_percent": 5
  },
  "error": "Payment required"
}

The trailing error field is a plain string banner, not an OpenAI error object. A second accepts entry (with escrow_program_id) only appears when the gateway has an escrow program configured.

A 402 returned for an invalid payment header (malformed, replayed, expired, amount-insufficient, etc.) uses the conventional OpenAI envelope instead:

{
  "error": {
    "type": "invalid_payment",
    "message": "transaction has already been used; each payment signature may only be submitted once"
  }
}

Distinguish the two shapes by checking for the top-level x402_version field.

Your client should read accepts[0].amount for the atomic-unit value, accepts[0].pay_to for the destination wallet, and accepts[0].asset for the SPL mint. The max_timeout_seconds field tells you how long the signed transaction will be accepted before expiring.

Construct a USDC-SPL transfer for the exact amount to the pay_to address and sign it with your wallet's private key. The TypeScript SDK uses @solana/web3.js, the Python SDK uses solders, and the Rust CLI uses the solana crate. The Go SDK's built-in KeypairSigner (solvela.NewKeypairSigner(wallet, rpcURL)) signs escrow deposits over raw Solana JSON-RPC; the exact scheme is intentionally unimplemented in Go, so for direct transfers implementers reach for gagliardetto/solana-go (or any Solana RPC client) via a custom Signer — see the Go SDK page.

The signing step never broadcasts the transaction — it only produces a signed transaction bytes object. The gateway broadcasts it after verifying the signature is valid.

Build a PaymentPayload JSON object containing your signed transaction, base64-encode the JSON, and resend the original request with the encoded value in the payment-signature header.

curl -X POST https://api.solvela.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64-encoded-PaymentPayload-JSON>" \
  -d '{
    "model": "auto",
    "messages": [{ "role": "user", "content": "Hello" }]
  }'

The PaymentPayload envelope itself contains x402_version, resource, an accepted block (one entry from the 402 accepts array), and a payload field with the base64-encoded signed Solana versioned transaction bytes. The outer header value is base64-encoded JSON; the inner signed transaction is also base64 (Solana versioned-tx wire bytes). See x402 Protocol for the exact shape.

If the signature is valid and the nonce is fresh, the gateway verifies the transaction (validate + simulate), proxies the request to the upstream LLM, and streams the response back to you in standard OpenAI format. For the default exact scheme, the on-chain broadcast is deferred until after the response is delivered — you are not charged when the provider call fails. Escrow deposits are the exception: they must land on-chain before the request is served.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o-mini",
  "choices": [{
    "index": 0,
    "message": { "role": "assistant", "content": "Hello! How can I help?" },
    "finish_reason": "stop"
  }],
  "usage": { "prompt_tokens": 10, "completion_tokens": 8, "total_tokens": 18 }
}