> ## Documentation Index
> Fetch the complete documentation index at: https://ti-mm-mycompc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Send SOL to the gateway">
    Transfer SOL to the gateway wallet address. The amount you send becomes your credit balance, denominated in lamports.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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.

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

<Tip>
  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.
</Tip>

<Note>
  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.
</Note>