API Keys and Credits: Pre-Paid Balance System Explained

Understand how Solana AI Gateway converts SOL deposits into pre-paid API credits, how keys are claimed after wallet signature, and how each call debits your balance.

Solana AI Gateway runs on a pre-paid credit model. You send SOL to the gateway wallet, the network confirms the transfer, and the gateway mints an API key tied to your wallet. Every paid request debits a flat fee from your credit balance. This page walks through the full lifecycle: topping up, claiming, and spending.

How credits are created

1. Send SOL to the gateway

   Transfer SOL to the gateway wallet address. The amount you send becomes your credit balance, denominated in lamports.

2. Helius webhook records the payment

   The gateway listens for your transfer via the Helius webhook at /api/payments/helius-webhook. Once the transaction is confirmed, a pending claim row is created in Postgres with a plaintext API key.

3. Sign the challenge and claim

   Use the challenge-response flow to prove wallet ownership. The server releases the API key and moves it from pending to active.

Key lifecycle

State	What happens
Pending	A pending_claims row exists but no one has proven ownership yet.
Active	After a valid signature, the key is released and stored in api_keys with your credit balance.
Re-claimed	Sending more SOL updates the same wallet row, so you can top up and claim again with the same key.

How spending works

The gateway applies a flat price per paid call: 2,200,000 lamports (0.0022 SOL). The requirePayment middleware checks your key on every request:

1. Free tier first: New keys get up to 50 lifetime free calls and 15 per day. The middleware consumes a free call when available.
2. Paid tier after free: Once free calls are exhausted, the middleware deducts 2,200,000 lamports from credit_balance_lamports.
3. Insufficient balance: If your balance is below the flat fee, the request is rejected with HTTP 402 and instructions to top up.

{
  "error": "Payment required",
  "priceLamports": 2200000,
  "instructions": "Pass header 'x-api-key: <key>' with sufficient balance. To top up, send SOL to ...",
  "payTo": "Brpc8HoPo1d3Uiyo7kbERnjMqwLJJmbWxtwxHxzar6DU"
}

You can re-claim the same key indefinitely. Every new SOL deposit adds lamports to the existing api_keys row for your wallet, so there is no need to manage multiple keys.

The gateway stores only a SHA-256 hash of your key for lookups. The plaintext key is kept in pending_claims until you claim it, after which you must store it securely. If you lose it, send more SOL and claim again.