# WebSocket subscriptions

Connect to `wss://rpc.aeredium.io` for real-time push notifications. The protocol is the standard Ethereum `eth_subscribe` / `eth_unsubscribe` interface — any tool that supports Ethereum WebSocket subscriptions (ethers, viem, web3.js) will work without changes.

## Connect

```ts
import { createPublicClient, webSocket } from "viem";
import { aeredium } from "./chain";

const client = createPublicClient({
  chain: aeredium,
  transport: webSocket("wss://rpc.aeredium.io"),
});
```

Or with raw WebSocket from a script:

```bash
npx wscat -c wss://rpc.aeredium.io
```

```json
> {"jsonrpc":"2.0","id":1,"method":"eth_subscribe","params":["newHeads"]}
< {"jsonrpc":"2.0","id":1,"result":"0xabc..."}
< {"jsonrpc":"2.0","method":"eth_subscription","params":{"subscription":"0xabc...","result":{...block header...}}}
```

## Subscription types

### `newHeads`

Fires once per block (\~every 2 seconds).

```json
{ "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newHeads"] }
```

Payload is a block header without transactions. Useful for following the tip of the chain.

### `newPendingTransactions`

Fires for each transaction accepted into the mempool, before inclusion.

```json
{ "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions"] }
```

By default returns transaction hashes. Pass `true` as the second param for the full transaction object:

```json
{ "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["newPendingTransactions", true] }
```

### `logs`

Filter event logs as they're emitted. The filter object accepts the standard fields:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "eth_subscribe",
  "params": [
    "logs",
    {
      "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f3bA21",
      "topics": ["0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"]
    }
  ]
}
```

`address` accepts a single address or an array. `topics` follows the standard pattern (`null` = wildcard, array = OR).

### `syncing`

Fires when the node enters or leaves syncing state. On a healthy mainnet connection this almost always returns `false` immediately and won't fire again.

### `aer_anchorConfirmed` (AEREDIUM extension)

Fires whenever a Bitcoin anchor crosses the final-confirmation threshold (≥ 6 BTC blocks).

```json
{ "jsonrpc": "2.0", "id": 1, "method": "eth_subscribe", "params": ["aer_anchorConfirmed"] }
```

Payload is the anchor record (AEREDIUM block range, Bitcoin tx hash, confirmation count).

## Unsubscribe

```json
{ "jsonrpc": "2.0", "id": 2, "method": "eth_unsubscribe", "params": ["0xabc..."] }
```

The connection itself can also be closed — the server cleans up all subscriptions tied to it.

## Connection limits

* One client may have up to **20 active subscriptions**.
* Idle connections (no data flowing in either direction for 10 minutes) are closed.
* Reconnect with exponential backoff on disconnect; missed events between disconnect and reconnect can be backfilled via `eth_getLogs`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://aeredium.gitbook.io/developer.aeredium.io/json-rpc-api/websocket.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.