Quickstart

Get BlockWire integrated into your agent in under 5 minutes. This guide walks through subscribing to events and setting up your webhook.

Prerequisites

Before you begin, make sure you have:

A wallet with ETH on Base (for gas) and USDC (for subscription)
A publicly accessible webhook endpoint (HTTPS)
Node.js 18+ installed

Installation

Install the BlockWire SDK:

Terminal

npm install @echorift/blockwire ethers

Step-by-Step Guide

Initialize the Client

Create a BlockWire client with your agent's wallet.

TypeScript

import { BlockWireClient } from '@echorift/blockwire';
import { ethers } from 'ethers';

// Load your agent's private key
const provider = new ethers.JsonRpcProvider(
  'https://mainnet.base.org'
);
const wallet = new ethers.Wallet(
  process.env.AGENT_PRIVATE_KEY,
  provider
);

// Initialize BlockWire
const blockwire = new BlockWireClient({
  chain: 'base',
  signer: wallet,
});
                    

Create a Webhook Endpoint

Set up an endpoint to receive events. Here's a minimal Express example:

TypeScript

import express from 'express';
import { verifyWebhook } from '@echorift/blockwire';

const app = express();
app.use(express.json());

app.post('/blockwire', (req, res) => {
  // Verify the signature
  const signature = req.headers['x-blockwire-signature'];
  const timestamp = req.headers['x-blockwire-timestamp'];
  
  const isValid = verifyWebhook({
    payload: JSON.stringify(req.body),
    signature,
    timestamp,
    secret: process.env.WEBHOOK_SECRET,
  });

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process events
  const { events } = req.body;
  
  for (const event of events) {
    console.log(`[${event.type}]`, event.address);
    
    // Your agent logic here
  }

  res.status(200).send('OK');
});

app.listen(3000);
                    

Important

Your webhook must respond within 5 seconds. BlockWire does not retry failed deliveries — use attestations to replay missed events.

Subscribe to Events

Call subscribe() to register your webhook on-chain.

TypeScript

// Subscribe for 24 hours to contracts and liquidity events
const tx = await blockwire.subscribe({
  webhookUrl: 'https://my-agent.com/blockwire',
  eventTypes: ['contracts', 'liquidity'],
  hours: 24,
});

console.log('Subscribed!', tx.hash);
console.log('Expires at:', tx.expiresAt);
                    

Pricing

Subscriptions cost $0.10/hour in USDC. Make sure your wallet has sufficient USDC approved for the BlockWire contract.

Receive Events

Events will start arriving at your webhook within 30 seconds.

Here's an example webhook payload:

JSON

{
  "batch_id": "batch_12345678_12345700_a1b2c3d4",
  "timestamp": 1701500000,
  "block_range": {
    "start": 12345678,
    "end": 12345700
  },
  "events": [
    {
      "type": "new_contract",
      "address": "0x1234...abcd",
      "block": 12345680,
      "txHash": "0xdead...beef",
      "timestamp": 1701499800,
      "data": {
        "deployer": "0x5678...efgh"
      }
    }
  ],
  "attestation_pending": true
}
                    

Next Steps

Now that you're receiving events, explore these topics:

Webhook Verification — Deep dive into HMAC signatures
Attestations — Verify event authenticity on-chain
x402 Pull Mode — Query events without a subscription
Event Types — Full reference for all event categories