Client API
The routing layer the SDK runs on, for code that wants it on its own: batching, a standby route and failover, without verification. The whole surface is one async factory and the two methods on what it returns.
Set up
The client is one file, client/atmos.js, in the Atmos repository. It isn’t on npm. In the browser it needs a bundler that resolves npm packages (Vite, esbuild, webpack) and anon-rpc’s reference harness:
npm install @anon-rpc/browser-harness@0.4.0 Then copy client/atmos.js into your project. In Node, the worker runs in the Node harness instead.
Quick start
import { createAtmosClient } from "./atmos.js";
// Used once, by the harness, to read the worker's hash from the specifier contract.
// This one read is not anonymised: use a provider you already trust.
const bootstrapProvider = {
async request({ method, params }) {
const res = await fetch("https://ethereum-rpc.publicnode.com", {
method: "POST",
headers: { "content-type": "application/json" },
body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),
});
const body = await res.json();
if (body.error) throw new Error(body.error.message);
return body.result;
},
};
const RPC = "https://rpc.mevblocker.io";
const atmos = await createAtmosClient({ bootstrapProvider, probeUrl: RPC });
const reply = await atmos.request(RPC, {
jsonrpc: "2.0",
id: 1,
method: "eth_getBalance",
params: ["0x00000000219ab540356cBB839Cbe05303d7705Fa", "latest"],
});
console.log(reply.result);
// When the page is done with it:
atmos.close(); What happens on startup
createAtmosClient resolves once one route is proven to work. In practice that takes from about 10 seconds to a minute:
- It reads the Nym directory and keeps the entry gateways and exits in the top performance band.
- It picks an entry that answers a WebSocket, and an exit it hasn’t used yet.
- It boots the stock Nym worker on that pair and waits for
ready. - It sends
eth_chainIdtoprobeUrl, up to twice. Only a route that answers is accepted. This also warms the connection to that provider, so the first real call doesn’t pay for it. - Once the first route is accepted, a second one boots in the background as the standby.
If four routes in a row fail, createAtmosClient rejects with no working route.
Choosing providers
Atmos works with any JSON-RPC URL, but not every provider accepts traffic from mixnet exits. Measured on 2026-11-06:
| Provider | Accepts Nym exits | Notes |
|---|---|---|
rpc.mevblocker.io | yes | Clean on proofs as well as reads |
ethereum-rpc.publicnode.com | yes | Sometimes rejects eth_getProof near the head (error 4444) |
eth.drpc.org | yes | The free tier allows at most 3 calls per batch; Atmos respects that |
rpc.flashbots.net | yes | |
1rpc.io | no | Returns 403 to Nym exits |
Use the same URL for probeUrl as for your first calls, so the warm connection gets used.
createAtmosClient(options)
function createAtmosClient(options: {
bootstrapProvider: { request(args: { method: string; params?: unknown[] }): Promise<unknown> };
probeUrl: string;
log?: (event: AtmosEvent) => void;
}): Promise<AtmosClient>; | Option | Required | What it is |
|---|---|---|
bootstrapProvider | yes | An EIP-1193-style object. The harness uses it once per worker to read the worker hash from the specifier contract. That read is not anonymised. |
probeUrl | yes | A JSON-RPC URL. Each new route must answer eth_chainId here before it is used. |
log | no | Called with an event object whenever a route is accepted, rejected or failed over. |
It resolves once a first route is accepted, and rejects with Error("no working route") after four failed attempts. A standby route starts booting as soon as it resolves.
client.request(url, body)
request(url: string, body: JsonRpcRequest): Promise<JsonRpcResponse>; Sends one JSON-RPC call to url through the mixnet, and resolves to the provider’s JSON-RPC response object, { jsonrpc, id, result } or { jsonrpc, id, error }. Your id comes back unchanged, even when the call travelled inside a batch.
- A JSON-RPC error is a normal reply, not an exception.
requestresolves with it; checkreply.error. - It rejects when the route fails and nothing is left to retry on: the call timed out with no standby ready, the worker errored, or a batch reply had no member for this call (
missing batch member). - Calls to the same URL made in the same tick, or while another call to that URL is in flight, leave together as one JSON-RPC batch. See Routing & batching.
eth_sendRawTransactionis deduplicated while in flight (a second identical send returns the first send’s promise) and is never retried or moved to the standby route. In v1 it still shares the per-provider queue, so a write issued in the same tick as reads to the same URL joins their batch. Send writes to their own URL, or on their own tick, if that matters to you.
client.close()
Closes every worker: the primary, the standby, and any route still draining after a failover. Calls still in flight reject.
Events
log receives plain objects:
event | Other fields | When |
|---|---|---|
route-accepted | attempt, probe | A route answered its probe and is now usable |
route-rejected | attempt, reason | A route failed: boot timeout, a worker error, or probe |
failover | A call stalled or failed on the primary, and the standby took over |
const atmos = await createAtmosClient({
bootstrapProvider,
probeUrl: RPC,
log: (e) => console.debug("[atmos]", e),
}); Timeouts and limits
These are constants in v1, not options.
| Constant | Value | Meaning |
|---|---|---|
| Boot timeout | 120 s | Longest wait for a worker’s ready |
| Probe timeout | 24 s | Per probe call; two probes per route |
| Attempt timeout | 8 s | A call slower than this (or one that fails) moves to the standby route |
| Retire grace | 30 s | A replaced route stays open this long, so calls already on it can finish |
| Batch size | 10 (drpc: 3) | Most calls per JSON-RPC batch, per provider host |
| Gateway check | 5 s | An entry gateway must accept a WebSocket within this |
| Performance band | ≥ 0.99 | Minimum Nym directory score for entries and exits |
The worker
Atmos runs the Nym worker published at specifier 0x3aCD9742C68F6d993066Ae25533e09b9e1f60eD0 on mainnet, with preferredGateway and preferredIpr set from its own route choice. The bundle is fetched and hash-checked by the stock harness exactly as without Atmos.