# Solana Pulse AI Agent Gateway

Solana blockchain API and Model Context Protocol (MCP) server. Provides read-only lookups, transaction simulation, token metadata, priority-fee estimates, and transaction decoding on mainnet-beta and devnet.

## Pricing (x402, USDC on Solana)
- Free, rate-limited (120 requests per minute per IP): get_solana_balance, get_solana_blockhash, get_token_accounts, get_recent_transactions, find_ata, inspect_address.
- Every other tool: 3 free calls per caller (counted by IP address, shared between HTTP and MCP), then a per-call price in USDC:
  - get_wallet_snapshot: $0.001
  - summarize_wallet_activity: $0.001
  - resolve_token_symbol: $0.001
  - get_token_market_snapshot: $0.001
  - optimal_fee: $0.001
  - simulate_solana_transaction: $0.001
  - estimate_transaction_cost: $0.001
  - decode_tx: $0.005
  - explain_transaction_effects: $0.005
  - token_profile: $0.005
  - analyze_token_concentration: $0.005
  - compare_tokens: $0.005
  - analyze_wallet_portfolio: $0.005
  - validate_transaction: $0.01
- No account or API key. Pay per request with x402 v2 (scheme "exact", network solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp). Calls that return an error are not charged.

## HTTP API
- GET /api/solana/balance?wallet=<address> — native SOL balance.
- GET /api/solana/blockhash — latest finalized blockhash.
- GET /api/solana/token-accounts?wallet=<address> — SPL token accounts.
- GET /api/solana/transactions?wallet=<address> — recent signatures (maximum 50).
- GET /api/solana/find-ata?wallet=<address>&mint=<mint> — derive an ATA and check whether it exists.
- POST /api/solana/simulate — simulate a base64 serialized VersionedTransaction without broadcasting.
- POST /api/solana/validate-and-simulate — simulate a transaction and return a safety verdict with fix hints.
- GET /api/solana/token-profile?mint=<mint> — token details, mint authorities, risk signal, and top holders.
- GET /api/solana/optimal-fee — recent priority-fee estimates.
- GET /api/solana/decode-tx?signature=<signature> — transaction summary and balance changes.
- GET /api/trial/status — free calls used per tool for this caller, and each tool's price.

## MCP Tools (20)
- Core tools: get_solana_balance, get_solana_blockhash, get_token_accounts, get_recent_transactions, simulate_solana_transaction, find_ata, token_profile, optimal_fee, decode_tx, and validate_transaction.
- Intelligence tools: get_wallet_snapshot, summarize_wallet_activity, resolve_token_symbol, get_token_market_snapshot, analyze_token_concentration, compare_tokens, inspect_address, explain_transaction_effects, analyze_wallet_portfolio, and estimate_transaction_cost.
- Prices are listed under Pricing and in each tool description.

## Paying with x402
- HTTP: an unpaid call to a paid route returns 402 with a PAYMENT-REQUIRED header (base64 PaymentRequired). Retry with a PAYMENT-SIGNATURE header; the receipt comes back in PAYMENT-RESPONSE.
- MCP: an unpaid call returns a tool result with isError and the PaymentRequired object. Retry the call with the payment in _meta["x402/payment"]; the receipt comes back in _meta["x402/payment-response"].
- Client libraries such as @x402/fetch and @x402/mcp handle this automatically.

## Entry Points
- Streamable HTTP endpoint: POST /mcp
- MCP SSE Endpoint: /mcp/sse
- Tool Manifest: /.well-known/mcp.json