---
title: Server diagrams
category: reference
---

# Server diagrams

These diagrams give a visual overview of how `WalletAPIServer` brokers communication between a Live App and a wallet. Read them alongside the [server reference](./reference) and the [RpcNode reference](./extras/rpc-node).

> **Note:** The diagrams come from this [introductory slideshow](https://link.excalidraw.com/p/readonly/cU4iVB5H8XFM7eW7S7u4) and have been adapted to be readable on their own.

## 1. Direct wallet–app interaction

![Live App and wallet exchanging ad-hoc messages without an RPC layer, showing the lack of structure that motivates the Wallet API](./assets/diagram-request-handlers-1-light.png)

Without a JSON-RPC layer, every Live App and every wallet would need ad-hoc message contracts. The Wallet API exists to replace this with a structured, capability-based bridge.

## 2. Processing requests with requestHandlers

![The WalletAPIServer routing an incoming JSON-RPC request to the matching requestHandler before returning a response](./assets/diagram-request-handlers-2-light.png)

When the Live App sends a request, the server looks up [`requestHandlers`](./reference#requesthandlers) by method ID, runs the matching handler with the parsed parameters and `walletContext`, then writes the result back to the transport.

## 3. Asking the wallet for data or actions with walletHandlers

![A requestHandler delegating to a walletHandler, which performs an action on the wallet side and returns a result back through the server](./assets/diagram-wallet-handlers-1-light.png)

Most request handlers cannot fulfil a request alone: they need wallet-side capabilities such as prompting the user, signing, or reading accounts. They delegate to [`walletHandlers`](./reference#wallethandlers), which the wallet implements.

## 4. Bidirectional transport

![The Transport object carrying serialized JSON-RPC messages in both directions between the Live App and the wallet via send and onMessage](./assets/diagram-transport-1-light.png)

The [`transport`](./reference#transport) carries strings in both directions: the Live App's `send` becomes the server's `onMessage`, and vice versa. The transport itself is implementation-specific (postMessage, WebSocket, IPC).

## 5. Data and permissions flowing into walletContext

![Accounts, currencies, configuration, and permissions being injected into walletContext from setter calls on the wallet side](./assets/diagram-permissions-1-light.png)

The wallet pushes accounts, currencies, configuration, and permissions into the server using the matching setters. The server combines them into [`walletContext`](./reference#walletcontext), the read-only view that request handlers consume. Permissions filter both what handlers a Live App can call and what currencies and accounts they can see.

## See also

- [Server reference](./reference): full list of properties, methods, and the constructor signature.
- [RpcNode](./extras/rpc-node): the abstract class that handles JSON-RPC framing and error translation.
- [Server slideshow](https://link.excalidraw.com/p/readonly/cU4iVB5H8XFM7eW7S7u4): the original Excalidraw deck.