Claim a Solana API Key with Wallet Authentication

Top up your Solana wallet, sign a challenge with your keypair, and claim a credit-metered API key for the Solana Pulse AI Agent Gateway.

Solana Pulse AI Agent Gateway issues credit-metered API keys through wallet-based authentication. You top up by sending SOL to the gateway wallet, then sign a challenge with your Solana keypair to prove ownership and claim your key. This guide walks through the entire flow from funding to a working API key.

1. Top up your wallet

   Send SOL to the gateway wallet address to create a pending API key balance:

   Brpc8HoPo1d3Uiyo7kbERnjMqwLJJmbWxtwxHxzar6DU
   

   The gateway listens for your transfer via a Helius webhook. Once confirmed, a pending claim is created for your wallet address. You do not need to wait for a notification; the claim endpoint will tell you when your key is ready.

2. Fetch a challenge

   Request a random 32-byte challenge from the gateway. You will sign this value to prove ownership of your wallet.

   curl https://solana-pulse-ai-agent-gateway.ai.studio/api/keys/challenge
   

   Expected response:

   {
     "challenge": "a1b2c3d4e5f6..."
   }
   
3. Sign the challenge

   Use @solana/web3.js and tweetnacl to sign the challenge with your keypair. The signature must be base58-encoded.

   import { Keypair } from "@solana/web3.js";
   import nacl from "tweetnacl";
   import bs58 from "bs58";
   
   // Load your wallet keypair (replace with your own secret key)
   const secretKey = Uint8Array.from([/* 64-byte secret key */]);
   const keypair = Keypair.fromSecretKey(secretKey);
   const wallet = keypair.publicKey.toBase58();
   
   // Fetch challenge from gateway
   const challengeRes = await fetch("https://solana-pulse-ai-agent-gateway.ai.studio/api/keys/challenge");
   const { challenge } = await challengeRes.json();
   
   // Sign challenge
   const message = Buffer.from(challenge, "hex");
   const signature = nacl.sign.detached(message, keypair.secretKey);
   const signatureBase58 = bs58.encode(signature);
   
   console.log("Wallet:", wallet);
   console.log("Signature:", signatureBase58);
   
4. Claim your API key

   POST the wallet address, base58 signature, and challenge back to the gateway.

   const claimRes = await fetch("https://solana-pulse-ai-agent-gateway.ai.studio/api/keys/claim", {
     method: "POST",
     headers: { "Content-Type": "application/json" },
     body: JSON.stringify({
       wallet,
       signature: signatureBase58,
       challenge
     })
   });
   
   const claimData = await claimRes.json();
   console.log("API Key:", claimData.apiKey);
   

   Success response:

   {
     "apiKey": "3f2a1b4c...",
     "message": "Your secure API key has been claimed. Keep it secret!"
   }
   

   Store your API key securely. It is shown only once at claim time and cannot be retrieved again.

5. Use your key on paid endpoints

   Pass the key in the x-api-key header on every paid request:

   curl -H "x-api-key: 3f2a1b4c..." \
     "https://solana-pulse-ai-agent-gateway.ai.studio/api/solana/token-accounts?wallet=YOUR_WALLET&network=mainnet-beta"
   

Full end-to-end script

Here is a complete TypeScript script you can run with tsx or ts-node:

import { Keypair } from "@solana/web3.js";
import nacl from "tweetnacl";
import bs58 from "bs58";

const GATEWAY = "https://solana-pulse-ai-agent-gateway.ai.studio";

async function claimApiKey(secretKeyUint8: Uint8Array) {
  const keypair = Keypair.fromSecretKey(secretKeyUint8);
  const wallet = keypair.publicKey.toBase58();

  // 1. Fetch challenge
  const challengeRes = await fetch(`${GATEWAY}/api/keys/challenge`);
  const { challenge } = await challengeRes.json();

  // 2. Sign challenge
  const message = Buffer.from(challenge, "hex");
  const signature = nacl.sign.detached(message, keypair.secretKey);
  const signatureBase58 = bs58.encode(signature);

  // 3. Claim key
  const claimRes = await fetch(`${GATEWAY}/api/keys/claim`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ wallet, signature: signatureBase58, challenge })
  });

  if (!claimRes.ok) {
    const err = await claimRes.json();
    throw new Error(err.error || "Claim failed");
  }

  const { apiKey, message: msg } = await claimRes.json();
  console.log("Claimed!", msg);
  return apiKey;
}

// Replace with your actual secret key array
const MY_SECRET_KEY = Uint8Array.from([/* 64 bytes */]);
claimApiKey(MY_SECRET_KEY)
  .then(key => console.log("Store this key:", key))
  .catch(console.error);

Error handling

Status	Meaning	What to do
400	Missing wallet, signature, or challenge	Check your request body
401	Invalid signature	Verify you signed the exact challenge hex with the correct keypair
404	No pending key found	Send SOL to the gateway wallet and wait for confirmation
500	Server error	Retry after a moment

Result

You now have a credit-metered API key tied to your Solana wallet. Every paid call debits your balance by 0.0022 SOL (2,200,000 lamports). You also receive 50 lifetime free calls and 15 free calls per day before credits are consumed.

Next steps

• Decode a transaction to turn raw signatures into LLM-friendly summaries
• MCP Integration to connect the gateway to Claude Desktop or Cursor