Skip to main content
Solana AI Gateway separates endpoints into two tiers: public endpoints that anyone can call, and paid endpoints that require a valid API key with sufficient credits. The requirePayment middleware enforces this boundary on every request. This page lists the exact endpoints in each tier and explains how the middleware evaluates your key.

​
Free endpoints (no API key required)

These endpoints are open to all callers and do not debit credits: These endpoints are useful for health checks, onboarding flows, and MCP discovery before you ever send SOL. All of the following routes are protected by requirePayment(). You must include the header x-api-key: <your-key> on every call:

​
How the middleware decides

When a request hits a paid endpoint, requirePayment runs three checks in order:
  1. Extract the key: It reads x-api-key or the Bearer token from the Authorization header.
  2. Try free tier: If your key is active and you still have free calls remaining (50 lifetime, 15 per day), the request passes at no charge.
  3. Deduct credits: If free calls are exhausted, it subtracts 2,200,000 lamports from your balance. If the balance is too low, the request is blocked.
If any step fails, the middleware short-circuits and returns HTTP 402 with a JSON body telling you how to top up.

​
Best practices for high-volume agents

Pre-check credits

Before running a batch of paid tool calls, query your remaining balance indirectly by calling a free endpoint first, or pace your requests and handle 402 responses gracefully.

Cache free data

Blockhash and balance data change slowly. Cache free responses to avoid unnecessary paid calls for data you can refresh less often.
A 402 response means your key is either missing, invalid, or out of credits. Do not retry blindly. Top up by sending SOL to the gateway wallet, then claim or re-claim your key before resuming paid calls.