API Documentation
Stream Ethereum, BNB Chain, and Base pending transactions in real-time with your API key
Official Client Library
Need help?
info@chainpending.com🚀 Quick Start
- 1
Get your API key
Go to your dashboard and generate an API key
- 2
Choose your method
Use WebSocket for real-time streaming or HTTP for polling
- 3
Start streaming
Connect and receive pending transactions with full simulation logs
📡 WebSocket API (Recommended)
Real-time streaming of pending transactions. Best for applications that need instant updates.
Connection URL
Use network=bsc for BNB Chain or network=base for Base (Flashblocks - real-time for all tiers).
Example (JavaScript)
const ws = new WebSocket('wss://api.chainpending.com?apiKey=YOUR_API_KEY&network=bsc')
ws.onopen = () => {
console.log('Connected!')
}
ws.onmessage = (event) => {
const message = JSON.parse(event.data)
if (message.type === 'connected') {
console.log(`Connected with ${message.delay}s delay`)
}
if (message.type === 'pending_tx') {
const tx = message.data
console.log('New transaction:', tx.txHash)
console.log('Logs:', tx.logs.length)
// Process transaction here
}
}Message Types
Connected
Sent when you successfully connect
Pending Transaction
Each new pending transaction
Filtering (Subscribe Message)
After connecting, send a subscribe message to filter transactions. You will receive a confirmation when your filters are applied.
// Send after connecting:
ws.send(JSON.stringify({
"action": "subscribe",
"addresses": ["0xdAC17F958D2ee523a2206206994597C13D831ec7"],
"methods": ["0xa9059cbb"]
}))
// Server confirms:
// { "type": "subscribed", "filters": { "addresses": 1, "methods": 1 } }addresses — Filter by tx.from, tx.to, or contract addresses in event logs
methods — Filter by 4-byte function selector (e.g. 0xa9059cbb for transfer) or event topic hashes
Send empty arrays to clear filters and receive all transactions.
💡 Tip: WebSocket connections stay open and push transactions as they arrive. No need to poll!
🌐 HTTP REST API
Poll for recent pending transactions. Best for batch processing or when WebSocket isn't available.
Endpoint
Authentication
Include your API key in the X-API-Key header:
Query Parameters
| Parameter | Description | Example |
|---|---|---|
| limit | Max transactions (1-50) | ?limit=10 |
| addresses | Filter by address (tx.from, tx.to, or log contract) | ?addresses=0xabc... |
| methods | Filter by 4-byte function selector or event topic | ?methods=0xa9059cbb |
| network | Network to query (ethereum, bsc, base) | ?network=ethereum |
Example (cURL)
curl -H "X-API-Key: YOUR_API_KEY" \ "https://api.chainpending.com/stream?limit=10"
Example (JavaScript)
const response = await fetch('https://api.chainpending.com/stream?limit=10', {
headers: {
'X-API-Key': 'YOUR_API_KEY'
}
})
const data = await response.json()
console.log(`Received ${data.count} transactions`)
console.log('Transactions:', data.transactions)Response
{
"transactions": [
{
"txHash": "0x...",
"success": true,
"logs": [...],
"timestamp": 1762339912836,
"network": "ethereum"
}
],
"tier": "pro",
"delay": 6,
"network": "ethereum",
"count": 10
}⚠️ Note: HTTP polling is less efficient than WebSocket. For real-time needs, use WebSocket.
⏱️ Rate Limits
Rate limits apply to HTTP requests only. WebSocket connections have no rate limits.
| Tier | HTTP Rate Limit | Delay |
|---|---|---|
| Starter | 60 requests/minute | 10 seconds |
| Premium | 120 requests/minute | 6 seconds |
| Professional | 300 requests/minute | Real-time (0s) |
📦 Transaction Data
Each transaction includes fully simulated data with event logs
{
"txHash": "0x1234...",
"success": true,
"logs": [
{
"address": "0xabc...",
"topics": [
"0xc42079f94a6350d7e6235f29174924f928cc2ac818eb64fed8004e115fbcca67",
"0x000000000000000000000000..."
],
"data": "0x...",
"position": "0x0"
}
],
"timestamp": 1762339912836,
"network": "ethereum",
"error": null
}txHash
Transaction hash
success
Whether the simulation succeeded
logs
Array of event logs with topics and data
timestamp
Unix timestamp in milliseconds
✨ Best Practices
Use WebSocket for Real-Time
WebSocket is more efficient and provides instant updates
Implement Reconnection Logic
Handle disconnections gracefully with automatic reconnection
Use Filters
Filter by addresses or methods to reduce unnecessary data
Decode Event Logs
Use ethers.js or web3.js to decode the raw log data
📚 Official TypeScript/JavaScript Library
We provide an official npm package with full TypeScript support, automatic reconnection, and built-in filtering.
✨ Features: WebSocket & HTTP clients, TypeScript support, automatic reconnection, filtering, metrics, and more!
Need Help?
Have questions or need support? We're here to help!
Email us at:
info@chainpending.com