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

# Paywall Model: Free vs Paid Endpoints in Solana AI Gateway

> Learn which Solana AI Gateway endpoints are free, which require API key credits, and how the payment middleware decides whether to let your request through.

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:

| Endpoint                    | What it does                                |
| --------------------------- | ------------------------------------------- |
| `GET /api/solana/balance`   | Fetch native SOL balance for a wallet.      |
| `GET /api/solana/blockhash` | Get the latest finalized blockhash.         |
| `GET /api/keys/challenge`   | Request a signing challenge.                |
| `GET /.well-known/mcp.json` | Read the MCP server manifest and tool list. |

These endpoints are useful for health checks, onboarding flows, and MCP discovery before you ever send SOL.

## Paid endpoints (API key + credits required)

All of the following routes are protected by `requirePayment()`. You must include the header `x-api-key: <your-key>` on every call:

| Endpoint                         | What it does                                                               |
| -------------------------------- | -------------------------------------------------------------------------- |
| `GET /api/solana/token-accounts` | List SPL token holdings for a wallet.                                      |
| `GET /api/solana/transactions`   | Fetch recent transaction signatures (max 50, default 10).                  |
| `POST /api/solana/simulate`      | Simulate a base64 transaction without broadcasting.                        |
| `GET /api/solana/find-ata`       | Derive the Associated Token Account for a wallet and mint.                 |
| `GET /api/solana/token-profile`  | Return token metadata, supply, top holders, and security flags.            |
| `GET /api/solana/optimal-fee`    | Get tiered priority-fee recommendations with congestion stats.             |
| `GET /api/solana/decode-tx`      | Decode a transaction signature into a human-readable summary and category. |

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

<CardGroup cols={2}>
  <Card title="Pre-check credits" icon="wallet">
    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.
  </Card>

  <Card title="Cache free data" icon="database">
    Blockhash and balance data change slowly. Cache free responses to avoid unnecessary paid calls for data you can refresh less often.
  </Card>
</CardGroup>

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