API Documentation

All endpoints use WebSocket and require the following header:

X-Puddle-Key: <your-api-key>

/mempool

Real-time stream of pending transactions.

URL

wss://puddle.network/mempool

Query Parameters

Parameter	Description
`to=0x...`	Filter by a single recipient address
`to=[0x...,0x...]`	Filter by up to 50 recipient addresses
`format=geth`	Normalize output to geth-style JSON (`hash`, `from`, `to`, `input` with `0x` prefix)

Code Examples

Python

import asyncio, json, websockets

async def main():
    url = "wss://puddle.network/mempool"
    headers = {"X-Puddle-Key": "<your-api-key>"}
    async with websockets.connect(url, extra_headers=headers) as ws:
        async for message in ws:
            tx = json.loads(message)
            print(tx)

asyncio.run(main())

JavaScript

const WebSocket = require("ws");

const ws = new WebSocket("wss://puddle.network/mempool", {
    headers: { "X-Puddle-Key": "<your-api-key>" }
});

ws.on("message", (data) => {
    const tx = JSON.parse(data);
    console.log(tx);
});

/receipts (experimental)

Real-time stream of transaction receipts as transactions get confirmed.

URL

wss://puddle.network/receipts

Note: Ethereum blocks are produced approximately every 12 seconds. After connecting, you may not receive any data for up to 12 seconds — this is expected.

Code Examples

Python

import asyncio, json, websockets

async def main():
    url = "wss://puddle.network/receipts"
    headers = {"X-Puddle-Key": "<your-api-key>"}
    async with websockets.connect(url, extra_headers=headers) as ws:
        async for message in ws:
            receipt = json.loads(message)
            print(receipt)

asyncio.run(main())

JavaScript

const WebSocket = require("ws");

const ws = new WebSocket("wss://puddle.network/receipts", {
    headers: { "X-Puddle-Key": "<your-api-key>" }
});

ws.on("message", (data) => {
    const receipt = JSON.parse(data);
    console.log(receipt);
});