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 your balance is too low, you'll receive a 402 Payment Required:

                    json
                

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

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.

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.