atmos

atmos

Anonymous Ethereum RPC that is fast enough to leave on.

Run it on your machine

curl -fsSL https://atmos.xavio.dev/install.sh | sh

Then add this to MetaMask as a Sepolia network

http://127.0.0.1:8545/11155111

Needs Node 24 or newer. Install guide

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:

  1. It reads the Nym directory and keeps the entry gateways and exits in the top performance band.
  2. It picks an entry that answers a WebSocket, and an exit it hasn’t used yet.
  3. It boots the stock Nym worker on that pair and waits for ready.
  4. It sends eth_chainId to probeUrl, 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.
  5. 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:

ProviderAccepts Nym exitsNotes
rpc.mevblocker.ioyesClean on proofs as well as reads
ethereum-rpc.publicnode.comyesSometimes rejects eth_getProof near the head (error 4444)
eth.drpc.orgyesThe free tier allows at most 3 calls per batch; Atmos respects that
rpc.flashbots.netyes
1rpc.ionoReturns 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>;
OptionRequiredWhat it is
bootstrapProvideryesAn 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.
probeUrlyesA JSON-RPC URL. Each new route must answer eth_chainId here before it is used.
lognoCalled 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. request resolves with it; check reply.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_sendRawTransaction is 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:

eventOther fieldsWhen
route-acceptedattempt, probeA route answered its probe and is now usable
route-rejectedattempt, reasonA route failed: boot timeout, a worker error, or probe
failoverA 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.

ConstantValueMeaning
Boot timeout120 sLongest wait for a worker’s ready
Probe timeout24 sPer probe call; two probes per route
Attempt timeout8 sA call slower than this (or one that fails) moves to the standby route
Retire grace30 sA replaced route stays open this long, so calls already on it can finish
Batch size10 (drpc: 3)Most calls per JSON-RPC batch, per provider host
Gateway check5 sAn entry gateway must accept a WebSocket within this
Performance band≥ 0.99Minimum 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.