• Reading the docs…
Start trading

API reference

RPC relay

A Solana JSON-RPC endpoint on the API, so a browser reads the chain and sends its wallet’s transactions without holding a provider key. Point any Solana client at the API’s /rpc.

Route#

POST /rpc#

Relays one JSON-RPC 2.0 request from the allowlist to the cluster and passes the cluster’s answer back as it came, integers past 2^53 included. The app’s Solana connection uses it, and Config.rpcUrl names it. With web3.js: new Connection('https://api.privium.io/rpc', 'confirmed'). The relay’s CORS allows the solana-client header web3.js adds to every request.

The body is RpcRequest. The answer is a JSON-RPC 2.0 response, { jsonrpc, id, result } or { jsonrpc, id, error: { code, message, data } }, which api.rpc parses as either. An error from the relay itself carries one of the codes below and no data; one from the cluster passes through unchanged, with its data when the cluster sends one, and api.rpc returns that data as it came.

TypeScript
const answer = await api.rpc({ jsonrpc: '2.0', id: 1, method: 'getSlot', params: [] })
if ('error' in answer) throw new Error(answer.error.message)
const slot = answer.result
Response
{
  "jsonrpc": "2.0",
  "result": 470449015,
  "id": 1
}

Methods#

The relay forwards getAccountInfo, getMultipleAccounts, getBalance, getTokenAccountBalance, getTokenAccountsByOwner, getSlot, getBlockHeight, getLatestBlockhash, isBlockhashValid, getFeeForMessage, getMinimumBalanceForRentExemption, getSignatureStatuses, getTransaction, getSignaturesForAddress, getGenesisHash, getVersion, simulateTransaction and sendTransaction. Any other method, getProgramAccounts among them, is refused.

getTokenAccountsByOwner reads one owner’s accounts of one mint: its params are exactly the owner’s address, a filter holding only mint, and a configuration with encoding jsonParsed and at most commitment (processed, confirmed or finalized) and a non-negative integer minContextSlot. A programId filter, or any other form, is refused.

Request
{"jsonrpc":"2.0","id":1,"method":"getTokenAccountsByOwner","params":["GmaDrppBC7P5ARKV8g3djiwP89vz1jLK23V2GBjuAEGB",{"mint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"},{"encoding":"jsonParsed"}]}

sendTransaction runs its preflight at confirmed, the commitment of the blockhash a deposit build carries, unless its configuration, an object when sent, names a preflightCommitment. Every other setting the call sends reaches the cluster unchanged.

sendTransaction counts as a write; every other method, simulateTransaction included, counts as a read. The relay carries requests over HTTP POST, one per call: confirm a transaction by polling getSignatureStatuses.

Limits#

  • One request per call. A batch is refused.
  • A body of at most 64 KiB.
  • 600 reads and 30 writes a minute per client, where the client is the caller’s address, or behind a proxy the last address the proxy appended.
  • A relayed call waits at most one second for the API’s share of its RPC budget, then is refused with Retry-After: 1.

/rpc sits outside the POST limit of /v1, and the API’s origin check applies to it as to every route: a browser on an origin the API does not serve gets the ORIGIN_NOT_ALLOWED envelope (Browsers and origins).

JSON-RPC errors#

  • -32700, HTTP 400: the body is not JSON.
  • -32600, HTTP 400: the body is not one request object with jsonrpc "2.0", a string or integer id, a method and array params. With HTTP 413, the body is over 64 KiB.
  • -32601, HTTP 400: the method is not relayed.
  • -32602, HTTP 400: a getTokenAccountsByOwner call outside its one accepted form, or a sendTransaction whose configuration is not an object.
  • -32005, HTTP 429 with Retry-After: the client is over its read or write limit, or the API’s RPC budget is spent.
  • -32603, HTTP 502: the cluster RPC is unavailable.

An answer whose id could not be read from the request carries id null.

Types#

RpcRequest#

Field Type Meaning
jsonrpc "2.0" The JSON-RPC version.
id string or number The request id, a string or an integer; the answer carries it back.
method string A relayed method.
params unknown[] (optional) The method's parameters, as an array.