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 error.message field contains a JSON-encoded PaymentRequired object. Parse it 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.

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.