# Azul, Base RPC Documentation

> The fastest, most reliable path to the Base sequencer. Free, no signup, single-digit-millisecond p50, milliseconds are money.

Endpoint: `https://rpc.baseazul.dev`
Chain: Base (chainId 8453, hex 0x2105)
Native currency: ETH
Block explorer: https://basescan.org

This file is a flat, machine-readable mirror of https://baseazul.dev/docs intended
for LLMs and coding agents. Sections match the on-page anchors. A short index
suitable for indexing is available at https://baseazul.dev/llms.txt.

---

## Getting started

### The endpoint

One HTTPS URL serves all standard JSON-RPC methods. Public traffic does not require
an API key. Privileged keys exist for higher limits and access to restricted
namespaces.

```
POST https://rpc.baseazul.dev
Content-Type: application/json
```

The endpoint is standard JSON-RPC 2.0. Body is a single request object or an array
(batch). Responses are gzip/zstd compressed when the client advertises support.

### First request

Sanity-check with a chainId call. You should see `0x2105` (decimal 8453).

```bash
curl -X POST https://rpc.baseazul.dev \
  -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}'

# → {"jsonrpc":"2.0","result":"0x2105","id":1}
```

### CORS

The endpoint sets `Access-Control-Allow-Origin: *`. Browser fetch works from any
origin. Preflight (`OPTIONS`) responds with `204` and a 24-hour max-age.

---

## Reference

### Method support

All standard `eth_*`, `net_*`, and `web3_*` methods are available on the public
path. Restricted namespaces are blocked unless you authenticate with an API key.

| Namespace | Status | Notes |
|-----------|--------|-------|
| `eth_*` | full | All standard reads, writes, filters |
| `net_*` | full | — |
| `web3_*` | full | — |
| `eth_sendRawTransaction` | full | Submission optimized for lowest inclusion latency |
| `eth_getLogs` | full | Up to 5,000-block window per call |
| `debug_*` | none | Blocked on public path. Available with API key. |
| `trace_*` | none | Parity-style traces not exposed. |
| `txpool_*` | none | Blocked on public path. |

Need `debug_*` or `trace_*` for production analytics? Reach out for an API key.
Present a key in the `X-API-Key` request header (or `?api_key=` on the WebSocket URL):

```bash
curl -s https://rpc.baseazul.dev \
  -H 'content-type: application/json' \
  -H 'X-API-Key: YOUR_KEY' \
  --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
```

### Rate limits

Per-IP limits on anonymous traffic. API-key holders bypass all of these.

| Bucket | Limit |
|--------|-------|
| Standard methods | 100 req/s sustained · burst 400 |
| Heavy methods | 10 req/s sustained. `eth_getLogs`, large `eth_call` |
| Batch size | 50 requests per batched call |
| Max response body | 50 MB · HTTP 413 if exceeded |
| Daily egress (anon) | 1 TB raw JSON / day · HTTP 503 once exhausted |
| API key | Bypasses every cap above |

Hitting the cap returns `-32005` with a `Retry-After` header. Back off with
jitter; don't spin.

### Batching

Batch up to **50** requests in a single POST. Useful for fan-out reads
(multicall warmup, ENS resolution, parallel `eth_call`). One TLS handshake, lower
tail latency.

```json
[
  {"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1},
  {"jsonrpc":"2.0","method":"eth_getBalance","params":["0xabc…","latest"],"id":2},
  {"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":3}
]
```

### eth_getLogs window

Max range is **5,000** blocks per call. Wider
ranges return `-32602`. Page through history by chunking the range and
parallelizing requests.

### Error codes

JSON-RPC errors follow standard codes. HTTP-level errors come back as raw responses.

| Code | Trigger |
|------|---------|
| `-32000` | Method blocked on public path (restricted namespace). |
| `-32005` | Rate limit exceeded. Back off or use an API key. |
| `-32601` | Method not found on the underlying node. |
| `-32602` | Invalid params. `eth_getLogs` window > 5,000 blocks is the usual culprit. |
| `-32603` | Internal error / routing temporarily unavailable. |
| `HTTP 413` | Response too large (>50 MB). Trim your request. |
| `HTTP 503` | Daily egress quota exhausted (anonymous only). Use a key. |

---

## Guides

### Add a fallback

Azul is single-region. For production, pair it with a paid provider. `viem`
has a built-in fallback transport: the first URL wins, and the second takes over on
error or timeout.

```typescript
import { createPublicClient, http, fallback } from 'viem';
import { base } from 'viem/chains';

export const client = createPublicClient({
  chain: base,
  transport: fallback([
    http('https://rpc.baseazul.dev'),                  // Azul, primary, fast, no logging
    http('https://mainnet.base.org'),       // Coinbase default, last resort
  ], { retryCount: 1, retryDelay: 100 }),
});
```

### Subscribe to new blocks

Don't poll `eth_blockNumber` in a tight loop. WebSocket subscriptions are early
access, shipping to design partners. Request a key if your workload depends on live
tip-follow and we'll bring you in. Here is the shape it takes:

```typescript
import { createPublicClient, webSocket } from 'viem';
import { base } from 'viem/chains';

const client = createPublicClient({
  chain: base,
  transport: webSocket('wss://rpc.baseazul.dev/ws?api_key=YOUR_KEY'),
});

const unwatch = client.watchBlockNumber({
  onBlockNumber: (n) => console.log('new tip', n),
});
```

### Page through eth_getLogs

Chunk wide ranges into 5,000-block windows and
parallelize. Concurrent batches are accepted up to your per-IP cap.

```typescript
async function getLogsRange(client, address, fromBlock, toBlock) {
  const PAGE = 5000;
  const tasks = [];
  for (let start = fromBlock; start <= toBlock; start += PAGE) {
    const end = Math.min(start + PAGE - 1, toBlock);
    tasks.push(client.getLogs({ address, fromBlock: start, toBlock: end }));
  }
  return (await Promise.all(tasks)).flat();
}
```

### Drop-in snippets (other libraries)

```typescript
// viem (public client)
import { createPublicClient, http } from 'viem';
import { base } from 'viem/chains';
export const client = createPublicClient({ chain: base, transport: http('https://rpc.baseazul.dev') });
```

```typescript
// ethers v6
import { JsonRpcProvider } from 'ethers';
const provider = new JsonRpcProvider('https://rpc.baseazul.dev');
```

```typescript
// wagmi
import { createConfig, http } from 'wagmi';
import { base } from 'wagmi/chains';
export const config = createConfig({
  chains: [base],
  transports: { [base.id]: http('https://rpc.baseazul.dev') },
});
```

```python
# web3.py
from web3 import Web3
w3 = Web3(Web3.HTTPProvider("https://rpc.baseazul.dev"))
```

---

## Architecture

### Routing model

Azul picks a propagation path to the Base sequencer for every request,
chosen for low latency and reliable inclusion. Reads and writes use separate paths,
each tuned to its own workload.

The result is fast inclusion and failover that holds up at one transaction or a
thousand.

### Sandwich resistance

Sandwich attacks skim value from your trades. They need a window: a pending
interval during which a searcher can see your transaction and wedge their own
ahead of it.

Azul minimizes that window. Transactions are not parked anywhere
inspectable for longer than necessary; the routing prioritizes getting them
included over making them visible.

Caveat: nothing protects against a sequencer-internal observer. Anti-sandwich here
means "minimize the public surface where someone can see your tx and react."

---

## Performance

Server-side latency targets (do not include client → Virginia network RTT). These
are targets, not measured values, until the endpoint opens:

- p50 latency target: 4ms
- p95 latency target: 15ms

Region: us-east-1 (Virginia). Live metrics are at https://baseazul.dev/status.

---

## Privacy

The RPC path retains nothing per-request:

- No IP addresses
- No request bodies (so: no wallet addresses, no contract addresses)
- No response bodies
- No cookies, sessions, or cross-request identifiers

We do count anonymous aggregate bytes/day in memory for the egress cap. That
counter resets daily and isn't attributed to any IP or request. Full posture
statement: https://baseazul.dev/privacy.

---

## Canonical URLs

- Home: https://baseazul.dev/
- For users: https://baseazul.dev/users
- For developers: https://baseazul.dev/developers
- Full docs (HTML): https://baseazul.dev/docs
- Full docs (markdown, this file): https://baseazul.dev/llms-full.txt
- Short docs index: https://baseazul.dev/llms.txt
- Live status: https://baseazul.dev/status
- Privacy: https://baseazul.dev/privacy

Last updated: 2026-10-13.