Quickstart

Prerequisites

Before you start, you need:

• A Solana wallet with a keypair (e.g. generated with solana-keygen new or solvela wallet init)
• USDC-SPL in that wallet on Solana mainnet (mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v)
• A small amount of SOL for transaction fees (Solana base fee is 5,000 lamports per signature — roughly 0.000005 SOL per call)

Install an SDK

The SDKs handle the payment handshake automatically. Pick your language:

Send a request without payment

First, send a request without any payment header. The gateway will respond with 402 Payment Required and tell you exactly what the request costs.

Parse the 402 response

The body is the PaymentRequired object — parse it directly to get the cost and the accepted payment schemes:

{
  "x402_version": 2,
  "resource": { "url": "/v1/chat/completions", "method": "POST" },
  "accepts": [
    {
      "scheme": "exact",
      "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp",
      "amount": "315",
      "asset": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
      "pay_to": "<gateway-recipient-wallet>",
      "max_timeout_seconds": 300
    }
  ],
  "cost_breakdown": {
    "provider_cost": "0.000300",
    "platform_fee": "0.000015",
    "total": "0.000315",
    "currency": "USDC",
    "fee_percent": 5
  },
  "error": "Payment required"
}

The amount field is in atomic USDC units (6 decimal places). 315 means $0.000315 USDC. The trailing error field is a plain string banner — not the OpenAI { error: { ... } } envelope.

Sign a Solana transaction

Build and sign a USDC-SPL transfer transaction to the pay_to address for the amount specified.

Resend with the payment signature

The SDKs handle this automatically. If you're implementing manually, encode your signed transaction as a JSON PaymentPayload, base64-encode it, and send it in the payment-signature header:

curl https://api.solvela.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64-encoded-PaymentPayload>" \
  -d '{
    "model": "openai/gpt-4o",
    "messages": [{"role": "user", "content": "Explain Solana in one sentence."}]
  }'

A successful response is standard OpenAI format. Gateway-specific metadata (request ID, model fallback used, session token) is returned in x-solvela-* response headers; the JSON body itself is unmodified for drop-in OpenAI compatibility.