APIs, JSON-RPC and node integration

How does a wallet know your balance?

It reads no disk: it sends a question to a node, which answers. JSON-RPC is a very simple protocol for that: "RPC" means remote procedure call (calling a function that runs elsewhere), and the messages are JSON. The version described here is 2.0 (the "JSON-RPC 2.0 specification"). Several families of nodes speak it: Ethereum-style nodes, those built on Substrate, and Bitcoin Core also offers a JSON-RPC interface with its own methods. Method names differ from one ecosystem to another.

In this workshop, the practice node uses made-up names: chain_blockNumber, chain_getBalance, chain_getBlockByNumber. Remember the shape, not the names. Another difference from Ethereum: here quantities (such as a block height) are JSON numbers, whereas Ethereum-style nodes write them as hexadecimal strings.

A request has four fields

{"jsonrpc":"2.0","method":"chain_getBalance","params":["0xAAAA…","latest"],"id":7}

• jsonrpc: always the string "2.0".
• method: the name of the procedure.
• params: the arguments, either a list (by position, as above) or an object (by name). Optional when there is nothing to pass.
• id: an identifier you choose (number or string). The server copies it into its reply, so you can match each answer to its question when several are in flight.

It is sent in the body of an HTTP POST with the header Content-Type: application/json, to the endpoint's address (<endpoint> below), for example with curl:

curl -s -X POST <endpoint> -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"chain_blockNumber","params":[],"id":7}'

A response has a result OR an error

{"jsonrpc":"2.0","result":"0x1f4","id":7}
{"jsonrpc":"2.0","error":{"code":-32601,"message":"Method not found"},"id":7}

A response holds result or error, never both. Here "0x1f4" is a hexadecimal number: 1×256 + 15×16 + 4 = 500. Ethereum-style nodes return most numbers this way, as a hexadecimal string; other ecosystems return JSON numbers. Read your node's documentation and convert explicitly: never add two hexadecimal strings.

A big value (a balance in the smallest unit) often exceeds what a JavaScript number can represent exactly; keep it as a string or a bigint until display. You will see this again in the TypeScript workshop.

Notifications and batches

• A request without an id is a notification: the server answers nothing. Useful to inform, useless to ask.
• A batch is an array of requests sent at once; the response is an array, in an order that is not guaranteed: you match by id. Handy to save round trips on a slow connection, but some providers cap the batch size.

What this does NOT guarantee

• JSON-RPC says nothing about the authenticity of the answer: a node can be wrong, late or lying. Nothing here proves that the announced balance is the chain's.
• The specification says nothing about HTTP: some servers answer "200" even for a JSON-RPC error. Do not trust the HTTP status alone; look at the body.
• A chain_getBalance method exists on no real node under that name; go read your own node's method list.

Recap: four fields in, result OR error out, id to match.

Three kinds of failure not to confuse

Your code sends a request and does not get what it wanted. Three very different situations.

1. The transport fails: no response, timeout, connection dropped. You do not even know whether the server received the request.
2. HTTP reports a problem: for example 429 (too many requests, you exceed the rate limit) or a 5xx code (the server is in trouble).
3. JSON-RPC answers with an error: the server did receive and understand that something is wrong. The error field holds a code (number) and a message (text for humans).

A program decides on the code, never by parsing the message text.

The standard codes

In addition, the specification reserves the range -32000 to -32099 for implementation-defined "server" errors. Codes in that range, and those outside the standard range ("insufficient funds", "nonce too low"…), differ from one node software to another: do not memorise them, read your node's documentation and test them.

What to do with each error?

Retrying a read, retrying a send

Reading a balance twice is harmless: a read is said to be idempotent. Sending a transaction again is more delicate, but your knowledge of the nonce helps: a signed transaction has a fixed hash and a fixed nonce. If you send it again, the network will not execute it twice. The node will rather answer "already known" or, if it is already included, "nonce too low". These replies are not failures: look the transaction up by its hash before concluding. By contrast, re-signing a new transaction with a fresh nonce on every attempt can create two payments: avoid it.

A worked example

A client successively receives:

1. {"jsonrpc":"2.0","error":{"code":-32602,"message":"Invalid params"},"id":3}: it forgot the second parameter. No new attempt; fix the code.
2. HTTP 429 with Retry-After: 4: wait at least 4 seconds.
3. No answer for 10 seconds: give up this attempt (the timeout), then retry after a growing wait.

What this does NOT guarantee

• The absence of an error is not proof of correctness: the node can answer without error and be wrong.
• An error code tells what the node saw; it does not tell what the chain will decide. A transaction accepted into the pool can still be dropped later.
• No node's table of codes applies to another.

Recap: classify the failure first (transport, HTTP, JSON-RPC), then decide to retry or to fix.

Ask every two seconds, or be told?

A block arrives, say, every 12 seconds. If your application asks "what is the height?" every 2 seconds, it sends 6 requests per block, 5 of which bring nothing new. On a limited connection, that wastes data allowance, and you risk the provider's rate limit.

A WebSocket is a connection that stays open after an initial HTTP exchange: server and client can send each other messages whenever they like. Many nodes offer subscriptions on it: you say once "tell me about every new block header", and the server pushes each event. On Ethereum-style nodes this is the eth_subscribe method with the topic "newHeads"; names vary by ecosystem.

A simplified subscription

The messages below are simplified and schematic: consult your node for the exact shape.

-> {"jsonrpc":"2.0","method":"<subscribe method>","params":["newHeads"],"id":1}
<- {"jsonrpc":"2.0","result":"0x9a","id":1}
<- {"jsonrpc":"2.0","method":"<notification method>","params":{"subscription":"0x9a","result":{"number":"0x64","hash":"0xaa…","parentHash":"0x99…"}}}

The first reply gives the subscription identifier. The following messages have no id: they are notifications, carrying the subscription identifier to say which subscription they belong to.

What happens when the connection drops

This is the heart of the job. A WebSocket can die without warning (mobile network change, an intermediate box that cuts idle connections). And above all:

• No catch-up. A subscription does not replay what you missed. After reconnecting, you must subscribe again and fill the gap with ordinary requests.
• Silence is ambiguous. No message for 40 seconds: no new block, or a dead connection? Set a timeout (for example two or three times the expected block interval) after which you consider the connection suspect and reopen it.

A worked catch-up example

You have processed blocks up to number 101. The connection drops, you reconnect, you subscribe again, and the first header received carries number 105. Blocks 102, 103 and 104 are missing: 105 − 101 − 1 = 3 blocks. You request them one by one (or in a batch) with the block-reading method, then process 105.

Reorganisations

The headers you receive can be replaced: two different blocks numbered 105, each with its hash, arrive one after the other. That is a chain reorganisation (you saw forks in the consensus workshops). A serious client keeps, for each block, its number, its hash and its parent's hash, and checks that the new block's parent is the one it stored at the previous number. Otherwise it walks back to the common point and undoes what it had recorded beyond it. This precaution assumes a chain with probabilistic finality (the case of proof-of-work chains and many others); on a chain with instant finality (some BFT protocols), a decided block never changes and this case does not arise.

This is why one waits for some number of confirmations (blocks built on top) before acting on money. The number depends on the chain and on what you risk; no universal value exists.

A reconnection loop (sketch)

async function follow(state: { lastDone: number }) {
  while (true) {
    let socket;
    try {
      socket = await connect();                // opens the WebSocket
      await subscribeToHeads(socket);          // subscribe again each time
      const head = await firstHead(socket);
      for (let n = state.lastDone + 1; n < head.number; n++) {
        await handleBlock(await getBlock(n));  // fill the gap
        state.lastDone = n;                    // progress recorded block by block
      }
      await handleBlock(head);
      state.lastDone = head.number;
      await consume(socket, state);            // updates state.lastDone at each block
    } catch (e) {
      await waitBeforeRetry();                 // see the next lesson
    } finally {
      socket?.close();                         // always close the old connection
    }
  }
}

Progress is recorded block by block in state: if consume throws midway (the usual case of a dropped connection), the next turn restarts from the last block actually processed, without replaying dozens. Even so, a block can still arrive twice (for example if the drop happens between processing and updating state): handleBlock must therefore be idempotent, that is, give the same result if it processes the same block twice.

What this does NOT guarantee

• A subscription guarantees neither completeness (messages may be missing) nor uniqueness (a block may arrive twice after a catch-up).
• A received header is not final.
• The WebSocket does not authenticate the data: same remark as for HTTP.

Recap: subscribe, detect silence, subscribe again, fill the gap, check parents.

Your endpoint will go down

An RPC provider has outages, maintenance windows, rate limits. Your application must plan for that day. Four tools.

1. Wait longer and longer, with randomness

Retrying immediately and endlessly makes the outage worse. We use exponential backoff: the wait doubles after each failure up to a cap. Example with a base of 0.5 s and a cap of 8 s: 0.5 → 1 → 2 → 4 → 8 → 8 → 8… seconds. We add randomness (jitter): wait a duration drawn at random between 0 and the computed value. Why? If 1,000 clients lose the connection at the same instant and all retry exactly on the same second, they rebuild together the spike that saturated the server.

2. Always a timeout and a bounded number of attempts

A request without a timeout can wait forever. Set a timeout (say 10 s), a maximum number of attempts, and at the end show a clear state to the user. A circuit breaker takes the idea further: after K failures in a row on an endpoint, stop calling it for a rest period and move on to the next.

3. Several endpoints, and a freshness check

Keep a list of providers (or a node of your own plus a provider) and switch between them. But an endpoint that answers is not necessarily up to date. Example: A reports height 1,000,120, B 1,000,121, C 1,000,050. C is 71 blocks behind: it answers without error, with stale data. A serious client compares heights and sets C aside.

4. Never trust a single source for an important decision

To credit a deposit or trigger a payment, ask two independent providers: request the hash of the same block (at a sufficient confirmation depth) and compare. If they agree, confidence rises; if they differ, do not act, and ask a third or wait. Honest limits: two providers may depend on the same upstream infrastructure, and agreement does not replace the cryptographic verification offered by a full node or a light client that you run yourself.

Rate limits

When the provider answers 429, honour Retry-After. Reduce your consumption: cache what does not change (an old block no longer changes), use batches, prefer subscriptions to polling, and do not launch hundreds of requests in parallel.

Privacy: the provider sees everything

An RPC provider sees your IP address, the list of addresses you look up, the methods called and the time. If your wallet shows five accounts, the provider learns that those five addresses are linked, and can tie them to your IP and to an identity. HTTPS (TLS) protects the path against intermediate observers; it hides nothing from the provider itself, since it is the one terminating the connection.

Mitigations, none perfect: run your own node; spread requests across several providers so none sees all your addresses; go through a relay that hides the IP; look up only what is necessary. Another point: an API key placed in the code of a web page is public, since every browser downloads it. It identifies an account, it does not protect a secret; limit it on the provider side (allowed domains, rate cap) or go through your own server.

What this does NOT guarantee

• More providers does not make an answer true: it lowers the probability of believing an isolated error.
• Randomness and backoff reduce the load of retries, they do not repair the outage.
• A local node removes the privacy leak toward a third party, but not your own network exposure.

Recap: backoff with jitter, bounded timeouts, several compared sources, and awareness of what each provider sees.