API Reference Overview — Solana AI Gateway

Base URL, authentication, response envelope, and endpoint categories for the Solana AI Gateway REST API and MCP transport.

The Solana AI Gateway exposes a REST API and an MCP (Model Context Protocol) transport for AI agents and developers. Every response includes a live_status field, and paid endpoints require an API key passed in the x-api-key header. This page covers the base URL, authentication model, rate limits, and error format so you can start integrating immediately.

Base URL

Use the same base URL for all REST endpoints and MCP discovery:

$GATEWAY_URL

In your requests, replace $GATEWAY_URL with your deployed gateway host (for example, https://your-gateway.example.com).

Authentication

• Public endpoints (balance, blockhash, MCP manifest) do not require a key.
• Paid endpoints require the header x-api-key: $API_KEY.
• Obtain a key by sending SOL to the gateway deposit address, then claiming it via wallet signature. See Claim API key for the full flow.

Response envelope

Every JSON response contains a live_status field:

Value	Meaning
SUCCESS	The request completed normally.
FAILED	An RPC or internal error occurred; check the error field.

Rate limits

The gateway applies credit metering per API key rather than fixed request caps:

• Each paid call debits a flat fee in lamports from your key balance.
• Free tier: up to 50 lifetime calls and 15 per day.
• When free calls are exhausted, the gateway deducts from your deposited SOL balance.
• If your balance is insufficient, the gateway returns 402 Payment required.

Error format

Errors share a consistent JSON shape:

{
  "error": "Human-readable message",
  "live_status": "FAILED"
}

Common HTTP status codes:

Code	Cause	What to do
400	Missing or invalid parameter. Response may include a hint field.	Check the hint and fix the request.
401	Invalid wallet signature during key claim.	Re-sign the challenge with the correct private key.
402	Insufficient credits or missing API key.	Top up your balance or include x-api-key.
404	Resource not found (mint, transaction, or pending key).	Verify the address or signature and retry.
500	RPC or internal failure.	Retry after a short delay; live_status will be FAILED.

Endpoint categories

Keys & Auth

Challenge and claim endpoints for wallet-authenticated API keys.

Solana RPC

Public and paid endpoints for balances, blockhashes, token accounts, and transactions.

Intelligence Tools

ATA derivation, token security profiles, optimal fees, transaction decoding, and simulation.

MCP

MCP manifest and SSE transport for agent auto-discovery.