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

# Authentication: Solana wallet signatures and API keys

> Solana AI Gateway authenticates clients with wallet-signed challenges. Learn how to claim, use, and rotate credit-backed API keys.

Solana AI Gateway uses a two-stage auth model. You prove wallet ownership with an Ed25519 signature to *claim* a credit-backed API key, then send that key on every subsequent request.

## The two stages

<Steps>
  <Step title="Claim (one-time, per key)">
    Request a challenge, sign it with your wallet, and POST the signature. The gateway verifies the signature and returns your API key exactly once.
  </Step>

  <Step title="Call (per request)">
    Send the API key in the `x-api-key` header. The paywall middleware validates the key and debits your credit balance.
  </Step>
</Steps>

## Sending the API key

Add the key as an HTTP header on every paid endpoint:

```bash theme={null}
curl -H "x-api-key: sk_live_..." \
  "$GATEWAY_URL/api/solana/token-profile?mint=<mint>"
```

Public endpoints (`/api/solana/balance`, `/api/solana/blockhash`, `/api/keys/challenge`) do not require a key.

## How signatures are verified

The server:

1. Decodes your wallet address as a Solana `PublicKey`.
2. Decodes the signature from base58.
3. Verifies `nacl.sign.detached.verify(challenge, signature, publicKey)`.
4. On success, atomically deletes the pending row and returns the key.

If the signature is invalid, you get `401 Invalid signature`. If no pending key exists for the wallet, you get `404 No pending key found`; top up the wallet first.

## Rotating a key

To rotate, top up the wallet again to provision a new pending key, then re-run the claim flow. Old keys remain valid until they run out of credits or are revoked server-side.

<Warning>
  Treat the API key like a bearer token. Anyone with the key can spend your credits until it is depleted.
</Warning>

## Related

<CardGroup cols={2}>
  <Card title="Wallet signatures" icon="signature" href="/concepts/wallet-signatures">
    The cryptography behind claim verification.
  </Card>

  <Card title="Keys and credits" icon="coins" href="/concepts/api-keys-and-credits">
    How balances are tracked and debited.
  </Card>
</CardGroup>