Documentation

SolanaProx gives you instant access to AI APIs using Solana for payments. No accounts, no API keys — your wallet is your identity.

Introduction

SolanaProx is a pay-per-use AI API gateway that accepts SOL and USDC payments. Instead of managing API keys and billing accounts, you simply connect your Solana wallet, deposit funds, and start making requests.

Every request includes your wallet address in the header. We check your balance, process the AI request, and deduct the cost automatically. It's that simple.

💡 Why Solana?

Fast transactions (~400ms), low fees (<$0.001), and a massive developer ecosystem. Your balance updates in real-time as soon as your deposit confirms.

Quick Start

Get up and running in under 2 minutes:

1. Get your wallet address

Open Phantom (or any Solana wallet) and copy your wallet address. It looks like: FjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX

2. Deposit funds

Send SOL or USDC to our deposit address:

Deposit Address 
FjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX
✓ Real-time detection

We use WebSocket subscriptions to detect deposits instantly. Your balance updates within seconds of the transaction confirming.

3. Make a request

bash 
curl -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: YOUR_WALLET_ADDRESS" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello, Claude!"}
    ]
  }'

Authentication

SolanaProx uses wallet-based authentication. There are no API keys to manage — your Solana wallet address is your identity.

Include your wallet address in the X-Wallet-Address header with every request:

Header 
X-Wallet-Address: YOUR_SOLANA_WALLET_ADDRESS

We verify your balance before processing each request. If you have sufficient funds, the request proceeds and the cost is deducted. If not, you'll receive a 402 Payment Required response with your current balance and the deposit address.

Check Balance

GET /api/balance/{wallet_address}

Returns the current balance for a wallet address, broken down by token type.

bash 
curl https://solanaprox.com/api/balance/YOUR_WALLET_ADDRESS
Response
json 
{
  "wallet": "FjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX",
  "balance_lamports": 50000000,
  "balance_usdc": 5000000,
  "balance_sol": 0.05,
  "balance_usdc_formatted": 5.0,
  "total_usd": 12.50,
  "deposit_address": "FjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX"
}
Field Type Description
balance_lamports integer SOL balance in lamports (1 SOL = 1,000,000,000 lamports)
balance_usdc integer USDC balance in micro-units (1 USDC = 1,000,000 micro-units)
balance_sol float SOL balance as decimal
balance_usdc_formatted float USDC balance as decimal
total_usd float Total balance converted to USD

Make AI Request

POST /v1/messages

Send a message to an AI model. Compatible with the Anthropic Messages API format.

Request Headers

Header Required Description
Content-Type Yes Must be application/json
X-Wallet-Address Yes Your Solana wallet address

Request Body

Field Type Required Description
model string Yes Model ID (e.g., claude-sonnet-4-20250514)
messages array Yes Array of message objects with role and content
max_tokens integer Yes Maximum tokens in response (max: 4096)
provider string No Force a provider: anthropic or openai
bash 
curl -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: YOUR_WALLET_ADDRESS" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Explain quantum computing in simple terms"}
    ]
  }'

Response Headers

Header Description
X-Cache HIT or MISS — cache hits get 50% discount
X-Cost-USD Actual cost deducted for this request

Insufficient Balance Response

If you include X-Wallet-Address but your balance is too low, you receive a 402 Payment Required with your wallet state:

json 
{
  "error": "insufficient_balance",
  "message": "Please deposit funds to continue",
  "current_balance": 0.001,
  "required": 0.003,
  "deposit_address": "FjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX",
  "accepted_tokens": ["SOL", "USDC"]
}

No Wallet Header — x402 Spec Response

Requests sent with no X-Wallet-Address header receive a Coinbase x402 spec-compliant 402. The response body and the X-PAYMENT-REQUIRED header carry the same JSON (base64-encoded in the header). x402-aware agents parse this automatically to discover payment requirements without any custom integration.

http — response headers 
HTTP/1.1 402 Payment Required
X-PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MSwiYWNjZXB0cyI6W3s...
Content-Type: application/json
json — body (identical to X-PAYMENT-REQUIRED decoded) 
{
  "x402Version": 1,
  "accepts": [{
    "scheme":             "exact",
    "network":            "solana",
    "maxAmountRequired":  "0.003",
    "resource":           "https://solanaprox.com/v1/messages",
    "description":        "Pay-per-request AI inference via Solana USDC",
    "mimeType":           "application/json",
    "payTo":              "FjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX",
    "maxTimeoutSeconds":  300,
    "asset":              "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    "outputSchema":       null
  }],
  "error": "payment_required"
}

The asset field is the USDC SPL token mint on Solana mainnet. Send exactly 0.003 USDC to payTo, then retry with X-Wallet-Address set to the wallet you paid from.

Capabilities

GET /api/capabilities

Returns information about available models, payment methods, and features. Useful for AI agents to discover the API.

Health Check

GET /health

Returns service health status and provider availability.

x402 Protocol

SolanaProx implements the Coinbase x402 payment protocol — the open HTTP standard for machine-readable payment requirements on the Solana network. x402-aware agents and wallets can discover, parse, and pay SolanaProx automatically with no custom integration code.

Listed on 402index.io

SolanaProx is registered on 402index.io — the public discovery directory for x402-compliant services. Any x402 client can find and pay SolanaProx at runtime, purely from the spec response.

x402 Payment Flow

For agents that handle x402 natively — no pre-deposit required:

  1. Send a POST to /v1/messages with no X-Wallet-Address header
  2. Receive HTTP 402 — decode X-PAYMENT-REQUIRED header (base64 → JSON)
  3. Read accepts[0].payTo, maxAmountRequired ("0.003"), and asset (USDC mint)
  4. Send 0.003 USDC to FjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX on Solana mainnet
  5. Wait for confirmation (~400 ms), then retry with X-Wallet-Address set to your wallet
Two integration paths

Deposit-and-use — deposit USDC once, make many requests. Best for high-frequency agents.
x402 per-request — pay 0.003 USDC per call, no pre-deposit. Best for one-off calls or x402-native clients.

bash — inspect x402 response 
# Step 1: trigger 402, decode the header
curl -si -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"hi"}],"max_tokens":1}' \
  | grep -i x-payment-required \
  | awk '{print $2}' | tr -d '\r' | base64 -d | python3 -m json.tool

# Step 2: after paying, retry with your wallet
curl -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: YOUR_WALLET" \
  -d '{"model":"claude-sonnet-4-20250514","messages":[{"role":"user","content":"hi"}],"max_tokens":100}'

402index Discovery

402index.io is the public registry for x402-compliant services. Listing there means any x402-aware agent can find SolanaProx without hardcoded URLs or credentials.

x402 Field SolanaProx Value
x402Version1
schemeexact
networksolana
maxAmountRequired"0.003" USDC
payToFjGCr4WojWt1dHbUaCbkFgSrrXBYvbNqY6TWsePyqDFX
assetEPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v (USDC SPL)
maxTimeoutSeconds300
resourcehttps://solanaprox.com/v1/messages

cURL Examples

Basic Chat

bash 
curl -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: YOUR_WALLET" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 500,
    "messages": [
      {"role": "user", "content": "Write a haiku about Solana"}
    ]
  }'

Multi-turn Conversation

bash 
curl -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: YOUR_WALLET" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "My name is Alice"},
      {"role": "assistant", "content": "Hello Alice! Nice to meet you."},
      {"role": "user", "content": "What is my name?"}
    ]
  }'

Using GPT-4

bash 
curl -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: YOUR_WALLET" \
  -d '{
    "model": "gpt-4-turbo",
    "max_tokens": 1024,
    "messages": [
      {"role": "user", "content": "Hello from GPT-4!"}
    ]
  }'

Python Examples

python 
import requests

WALLET = "YOUR_WALLET_ADDRESS"
BASE_URL = "https://solanaprox.com"

# Check balance
def get_balance():
    resp = requests.get(f"{BASE_URL}/api/balance/{WALLET}")
    return resp.json()

# Make AI request
def chat(message, model="claude-sonnet-4-20250514"):
    resp = requests.post(
        f"{BASE_URL}/v1/messages",
        headers={
            "Content-Type": "application/json",
            "X-Wallet-Address": WALLET
        },
        json={
            "model": model,
            "max_tokens": 1024,
            "messages": [{"role": "user", "content": message}]
        }
    )
    return resp.json()

# Usage
print(get_balance())
print(chat("Explain blockchain in one sentence"))

JavaScript Examples

javascript 
const WALLET = 'YOUR_WALLET_ADDRESS';
const BASE_URL = 'https://solanaprox.com';

// Check balance
async function getBalance() {
  const resp = await fetch(`${BASE_URL}/api/balance/${WALLET}`);
  return resp.json();
}

// Make AI request
async function chat(message, model = 'claude-sonnet-4-20250514') {
  const resp = await fetch(`${BASE_URL}/v1/messages`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Wallet-Address': WALLET
    },
    body: JSON.stringify({
      model,
      max_tokens: 1024,
      messages: [{ role: 'user', content: message }]
    })
  });
  return resp.json();
}

// Usage
getBalance().then(console.log);
chat('Hello!').then(console.log);

With Phantom Wallet (Browser)

javascript 
// Connect Phantom and get wallet address
async function connectAndChat() {
  const provider = window.phantom?.solana;
  
  if (!provider?.isPhantom) {
    window.open('https://phantom.app/', '_blank');
    return;
  }

  const { publicKey } = await provider.connect();
  const wallet = publicKey.toString();

  // Now make requests with the wallet
  const response = await chat('Hello!', wallet);
  console.log(response);
}

OpenAI-Compatible SDK

Drop-in replacement for the OpenAI npm package. Change two lines — everything else stays identical.

bash 
npm install solanaprox-openai
javascript 
// Before (OpenAI):
import OpenAI from 'openai'
const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

// After (Solana):
import OpenAI from 'solanaprox-openai'
const client = new OpenAI({ apiKey: process.env.SOLANAPROX_WALLET_ADDRESS })

// Everything else stays identical:
const response = await client.chat.completions.create({
  model: 'claude-sonnet-4-20250514',
  messages: [{ role: 'user', content: 'Hello' }]
})
console.log(response.choices[0].message.content)

Your wallet address is your API key — no credentials to manage, no accounts. npmjs.com/package/solanaprox-openai

Streaming Responses

SolanaProx supports streaming responses for real-time token-by-token output. This provides a much better user experience for chat applications.

🚀 Why Streaming?

Streaming responses feel 5x faster. Instead of waiting 10 seconds for a complete response, users see text appearing immediately, word by word.

Enable Streaming

Add "stream": true to your request:

bash 
curl -X POST https://solanaprox.com/v1/messages \
  -H "Content-Type: application/json" \
  -H "X-Wallet-Address: YOUR_WALLET_ADDRESS" \
  -d '{
    "model": "claude-sonnet-4-20250514",
    "max_tokens": 500,
    "stream": true,
    "messages": [{"role": "user", "content": "Write a haiku about Solana"}]
  }'

Streaming Response Format

Responses are sent as Server-Sent Events (SSE):

text 
data: {"type":"content_block_delta","delta":{"text":"Purple"}}

data: {"type":"content_block_delta","delta":{"text":" chains"}}

data: {"type":"content_block_delta","delta":{"text":" move"}}

data: {"type":"message_stop"}

data: [DONE]

JavaScript Streaming Example

javascript 
const response = await fetch('https://solanaprox.com/v1/messages', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Wallet-Address': walletAddress
  },
  body: JSON.stringify({
    model: 'claude-sonnet-4-20250514',
    max_tokens: 500,
    stream: true,
    messages: [{ role: 'user', content: prompt }]
  })
});

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value);
  const lines = chunk.split('\n');
  
  for (const line of lines) {
    if (line.startsWith('data: ') && !line.includes('[DONE]')) {
      const data = JSON.parse(line.slice(6));
      if (data.delta?.text) {
        console.log(data.delta.text); // Print each token
      }
    }
  }
}
📝 Note

Streaming requests cannot be cached. The 50% cache discount only applies to non-streaming requests with identical queries.

Models & Pricing

We support multiple AI models. Pricing is based on the provider's token costs plus a 20% markup.

Model Provider Input (per 1M) Output (per 1M)
claude-sonnet-4-20250514 Anthropic $3.00 $15.00
claude-3-5-sonnet-20241022 Anthropic $3.00 $15.00
gpt-4-turbo OpenAI $10.00 $30.00
💰 Cache Discount

Repeated identical requests are served from cache at 50% off. Check the X-Cache: HIT response header.

Error Codes

Code Meaning Solution
400 Bad Request Check your JSON format and required fields
402 Payment Required Insufficient balance — deposit more funds
429 Too Many Requests Rate limited — wait and retry (10 req/min per IP)
500 Server Error AI provider issue — retry in a moment
503 Service Unavailable Spending limit reached or provider down

FAQ

How fast do deposits credit?

We use WebSocket subscriptions to detect deposits in real-time. Your balance typically updates within 2-5 seconds of the transaction confirming on Solana.

Which token should I use?

USDC is recommended for predictable pricing — 1 USDC always equals $1.00. SOL works great too, but the USD value fluctuates with the market.

Is there a minimum deposit?

No minimum. Deposit any amount. A typical request costs ~$0.003, so even $1 gets you hundreds of requests.

Can I get a refund?

Deposits are non-refundable, but your balance never expires. Use it whenever you want.

Is my wallet address public?

Solana wallet addresses are public by design. We only store your address and balance — no private keys, no personal information.

What happens if the AI provider is down?

We have circuit breakers that detect provider outages. If one provider fails, we'll return a clear error. Your balance is only deducted for successful requests.

Do you support streaming responses?

Yes! Add "stream": true to your request. Responses are delivered as Server-Sent Events (SSE) for real-time token-by-token output. See the Streaming section above.