API Overview

Architecture

TheRPC's Solana API follows the JSON-RPC 2.0 specification: you POST a request whose params are a positional array, and you get back a single JSON response. Four traits define the surface. First, it exposes both a standard HTTP endpoint for request/response calls and a WebSocket PubSub endpoint for real-time subscriptions. Second, every request is authenticated with your API key. Third, many read methods don't return a bare value — they wrap it in an RpcResponse envelope that pairs the data with the context slot it was read at. Fourth, the same surface is available across Solana's clusters — mainnet, devnet, and testnet — by switching only the endpoint URL.

Communication Protocols

The HTTP endpoint serves the bulk of Solana methods — every read like getAccountInfo, getBalance, and getBlock, plus the write path sendTransaction. It's the right choice for single requests, scripts, and simple integrations where you ask a question and get one answer back. See the HTTP/Curl guide for ready-to-run request examples.

HTTP Endpoint

https://solana.therpc.io/YOUR_API_KEY

The WebSocket PubSub endpoint serves the *Subscribe and *Unsubscribe methods, which push real-time notifications instead of making you poll. When you call a method such as accountSubscribe, the server replies with a numeric subscription id; from then on it pushes *Notification messages over the same connection, each tagged with that id so you can route updates to the right handler. To stop, call the matching *Unsubscribe with the id. See the accountSubscribe reference for a complete subscription example.

WebSocket Endpoint

wss://solana.therpc.io/YOUR_API_KEY

JSON-RPC Format

Every Solana call uses the JSON-RPC 2.0 format with a positional params array — arguments are passed in order, not as a named object. A request has four fields: jsonrpc, always the string "2.0"; id, a client-chosen value echoed back so you can match responses to requests; method, the name of the method to invoke such as getAccountInfo; and params, the positional array of arguments, where later entries (like an options object) refine the call.

Request Structure

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "method": "getAccountInfo",
5  "params": [
6    "9WzDXwBbmkg8ZTbNMqUxvQRAyrZzDsGYdLVL9zYtAWWM",
7    { "encoding": "base64" }
8  ]
9}

Response Format

All responses share the same shape: jsonrpc set to "2.0", the id echoed from your request, and exactly one of result (on success) or error (on failure). Many Solana read methods don't put the raw value directly in result — they wrap it in an RpcResponse envelope of the form { context: { slot, apiVersion }, value }, where context.slot tells you the slot the data reflects and value holds the actual payload. Knowing whether a method returns a bare value or an RpcResponse saves you a common parsing mistake.

Success Response (RpcResponse)

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "result": {
5    "context": { "slot": 250000000, "apiVersion": "2.0.0" },
6    "value": 1000000000
7  }
8}

Error Response

1{
2  "jsonrpc": "2.0",
3  "id": 1,
4  "error": {
5    "code": -32602,
6    "message": "Invalid params"
7  }
8}

Commitment and Encoding

• commitment — chooses how settled the data must be before it's returned: processed (most recent, may be dropped), confirmed (voted on by a supermajority), or finalized (rooted and irreversible). Most reads default to finalized.
• encoding — selects the format for account and transaction data: base58 (only for data ≤128 bytes), base64 (the recommended default), base64+zstd (compressed for large accounts), or jsonParsed (human-readable structured output where a parser exists, e.g. SPL token accounts).
• dataSlice and minContextSlot — further scope a read: dataSlice returns only an offset/length window of an account's data to cut payload size, and minContextSlot makes the call fail rather than return data older than a slot you specify.

Authentication

Every request carries your API key in the Solana endpoint URL path — https://solana.therpc.io/YOUR_API_KEY — and you can optionally pass it instead as a Bearer token in the Authorization header. The same key authenticates the wss:// WebSocket endpoint. See the full Authentication guide for key generation, placement, and security best practices.

Authorization Header

1Authorization: Bearer YOUR_API_KEY

Method Categories

The HTTP methods fall into a few natural groups: accounts (getAccountInfo, getBalance), tokens (getTokenAccountsByOwner and the SPL token reads), transactions (sendTransaction, getTransaction), blocks and slots (getBlock, getSlot), and cluster and economics (getEpochInfo, getSupply). Over WebSocket, the PubSub group covers accountSubscribe, programSubscribe, logsSubscribe, signatureSubscribe, and slotSubscribe, each paired with its *Unsubscribe counterpart. Every method name links to its own documentation page with parameters, response shape, and examples.

Error Handling

Errors arrive as JSON-RPC error objects with five standard codes: -32700 parse error (malformed JSON), -32600 invalid request (not a valid request object), -32601 method not found (unknown method name), -32602 invalid params (wrong or missing arguments), and -32603 internal error. When sendTransaction fails its preflight simulation, the error carries Simulation-Results data — logs and the underlying instruction error — so you can see exactly why the transaction would have failed before it was submitted. See the FAQ for detailed error-handling strategies.

Implementation Examples

• JavaScript / TypeScript — build on the @solana/web3.js Connection class.
• Python — use solana-py with solders for typed account and transaction handling.
• HTTP / curl — send raw JSON-RPC requests directly to the Solana endpoint.
• All SDKs — see the Tools & SDKs reference for Rust (solana-client), Go (solana-go), and more.