Quickstart: Claim a key and call the Solana AI Gateway

Top up a wallet, claim an API key with a Solana signature, and make your first authenticated call to the gateway in under five minutes.

This quickstart walks you from a fresh Solana wallet to a working authenticated call against the Solana AI Gateway. You will fund a wallet, prove ownership with a signature, and query a paid endpoint.

Prerequisites

• Node.js 18+ or Bun
• A Solana wallet (Phantom, Solflare, or a keypair file)
• The gateway base URL (self-hosted or your deployment)

1. Top up your wallet

   Send SOL to the gateway’s deposit address. Once the on-chain deposit is detected, a pending API key is provisioned for your wallet and stored server-side until you claim it.

2. Request a challenge

   The server issues a one-time random challenge that you must sign with your wallet’s private key.

   curl "$GATEWAY_URL/api/keys/challenge"
   

   Response

   { "challenge": "a1b2c3...32-byte-hex" }
   
3. Sign the challenge and claim your key

   Sign the raw challenge bytes with Ed25519, then POST the wallet address, base58 signature, and the original challenge back to the gateway.

   TypeScript

   import nacl from "tweetnacl";
   import bs58 from "bs58";
   
   const msg = Buffer.from(challenge);
   const sig = nacl.sign.detached(msg, keypair.secretKey);
   
   const res = await fetch(`${GATEWAY_URL}/api/keys/claim`, {
     method: "POST",
     headers: { "content-type": "application/json" },
     body: JSON.stringify({
       wallet: keypair.publicKey.toBase58(),
       signature: bs58.encode(sig),
       challenge,
     }),
   });
   const { apiKey } = await res.json();
   

   The response contains your API key. Store it securely; the pending record is deleted after claim.

4. Make your first authenticated call

   Pass the key on any paid endpoint. Try the token profile tool for a well-known mint.

   curl -H "x-api-key: $API_KEY" \
     "$GATEWAY_URL/api/solana/token-profile?mint=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
   

   You get back the mint’s decimals, supply, security flags, and top holders.

What just happened

• The gateway verified you own the wallet by validating your Ed25519 signature over the server-issued challenge.
• Your pending key was released from the pending_claims table and returned once.
• The paid endpoint debited your credit balance and returned processed intelligence, not raw RPC.

Next steps

Authentication

Header formats, key rotation, and error responses.

Intelligence tools

Full reference for the agent-facing endpoints.

/