Skip to content

Guide — Event Explorer

Use the Event Explorer

The Event Explorer is a public service that gives you structured access to everything that has happened on the Settlement Contract. Two interfaces — a REST API for historical queries and a WebSocket for real-time streaming — plus a TypeScript SDK that wraps both.

You do not need a wallet, a signing key, or any blockchain interaction to use it. Connect, query, and build.

What you can do with it

Use case Interface
Reconciliation dashboard REST — query settlements by merchant wallet
Real-time settlement feed WebSocket — stream new events as they confirm
Order confirmation WebSocket — watch for a specific order reference
Compliance reporting REST — filter by date range, token, amount
Local matching engine WebSocket — receive all settlements, process locally
Analytics and charting REST — aggregate by time window
Debugging REST — look up a specific transaction hash

Prerequisites

  • Node.js 18+ (for SDK usage)
  • An Explorer endpoint — use https://explorer.stablecoinstack.org for the public demo, or your local instance at http://localhost:4001

SDK quickstart

Install the SDK:

npm install @stablecoin-stack/explorer-sdk

Stream all new settlements in real time:

import { ExplorerClient } from '@stablecoin-stack/explorer-sdk';

const client = new ExplorerClient({
  baseUrl: 'https://explorer.stablecoinstack.org',
});

// Stream new settlements as they confirm
client.onSettlement((event) => {
  console.log(`Settled: ${event.amount} ${event.tokenSymbol}`);
  console.log(`  → recipient: ${event.recipient}`);
  console.log(`  → fee: ${event.fee}`);
  console.log(`  → block: ${event.blockNumber}`);
  console.log(`  → tx: ${event.txHash}`);
});

// Start streaming
await client.connect();

That is the entire setup. No authentication. No configuration beyond the endpoint URL.

REST API reference

Base URL

https://explorer.stablecoinstack.org   # public demo
http://localhost:4001                  # local development

All endpoints return JSON. All amounts are strings in token units.

GET /events

Returns historical settlement events, most recent first.

Query parameters:

Parameter Type Description
limit integer Records to return (default: 20, max: 100)
cursor string Pagination cursor from a previous response
token address Filter by token contract address
recipient address Filter by merchant/recipient wallet
payer address Filter by payer wallet
orderReference hex Filter by 16-byte order reference
acquirerId hex Filter by acquirer ID
fromBlock integer Starting block number
toBlock integer Ending block number
fromTimestamp integer Unix timestamp lower bound
toTimestamp integer Unix timestamp upper bound

Example — all recent settlements:

curl "https://explorer.stablecoinstack.org/events?limit=5"

{
  "events": [
    {
      "txHash":         "0xabc...123",
      "blockNumber":    12345678,
      "timestamp":      1780000042,
      "token":          "0x2791...",
      "tokenSymbol":    "USDC",
      "tokenDecimals":  6,
      "payer":          "0xPAYER...",
      "recipient":      "0xMERCHANT...",
      "amount":         "10000000",
      "fee":            "2500000",
      "orderReference": "0xdeadbeef00000000000000000000000000000000000000000000000000000000",
      "acquirerId":     "0x00000000000000000000000000000000",
      "domainSeparator":"0x..."
    }
  ],
  "nextCursor": "eyJibG9ja...",
  "total": 1247
}

Example — all settlements to a specific merchant:

curl "https://explorer.stablecoinstack.org/events?recipient=0xMERCHANT...&limit=50"

Example — settlements in a date range:

curl "https://explorer.stablecoinstack.org/events?fromTimestamp=1779000000&toTimestamp=1780000000"

GET /events/:txHash

Returns the settlement event for a specific transaction hash.

curl "https://explorer.stablecoinstack.org/events/0xabc...123"

Returns a single event object, or 404 if the transaction hash does not correspond to a settlement.

GET /events/order/:orderReference

Returns the settlement event for a specific order reference.

curl "https://explorer.stablecoinstack.org/events/order/0xdeadbeef..."

Useful for confirming a specific payment from a merchant reconciliation system.

GET /stats

Returns aggregate statistics.

curl "https://explorer.stablecoinstack.org/stats"

{
  "totalSettlements": 12487,
  "totalVolume": {
    "USDC": "124870000000"
  },
  "totalFees": {
    "USDC": "31217500000"
  },
  "last24h": {
    "settlements": 347,
    "volume": { "USDC": "3470000000" }
  }
}

WebSocket API

Connect to wss://explorer.stablecoinstack.org/stream (or ws://localhost:4001/stream locally).

No authentication required. Send a subscription message to start receiving events.

Subscribe to all settlements

const ws = new WebSocket('wss://explorer.stablecoinstack.org/stream');

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: 'SUBSCRIBE',
    channel: 'settlements',
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'SETTLEMENT') {
    console.log('New settlement:', msg.data);
  }
};

Subscribe to a specific recipient

ws.send(JSON.stringify({
  type: 'SUBSCRIBE',
  channel: 'settlements',
  filter: {
    recipient: '0xMERCHANT...',
  },
}));

Subscribe to a specific order reference

Useful for watching a single payment confirm:

ws.send(JSON.stringify({
  type: 'SUBSCRIBE',
  channel: 'settlements',
  filter: {
    orderReference: '0xdeadbeef...',
  },
}));

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  if (msg.type === 'SETTLEMENT') {
    console.log('Your order settled:', msg.data.txHash);
    ws.close();
  }
};

SDK — full API reference

Constructor

const client = new ExplorerClient({
  baseUrl: 'https://explorer.stablecoinstack.org',
  // Optional:
  wsUrl:   'wss://explorer.stablecoinstack.org/stream',  // defaults to baseUrl with wss://
  timeout: 10000,  // REST request timeout in ms
});

REST methods

// Query events
const result = await client.getEvents({
  limit: 20,
  recipient: '0xMERCHANT...',
  fromTimestamp: Date.now() / 1000 - 86400,  // last 24 hours
});

// Get a specific event
const event = await client.getEventByTxHash('0xabc...123');

// Get event for an order
const event = await client.getEventByOrderReference('0xdeadbeef...');

// Get statistics
const stats = await client.getStats();

WebSocket methods

// Connect
await client.connect();

// Subscribe to all settlements
client.onSettlement((event) => { ... });

// Subscribe filtered by recipient
client.onSettlement({ recipient: '0xMERCHANT...' }, (event) => { ... });

// Subscribe filtered by order reference (one-shot pattern)
client.onSettlement({ orderReference: '0x...' }, (event) => {
  console.log('Confirmed:', event.txHash);
  client.disconnect();
});

// Disconnect
client.disconnect();

Practical examples

Merchant reconciliation script

import { ExplorerClient } from '@stablecoin-stack/explorer-sdk';

const client = new ExplorerClient({ baseUrl: 'https://explorer.stablecoinstack.org' });

async function dailyReconciliation(merchantWallet: string, date: Date) {
  const startOfDay = new Date(date);
  startOfDay.setHours(0, 0, 0, 0);
  const endOfDay = new Date(date);
  endOfDay.setHours(23, 59, 59, 999);

  const result = await client.getEvents({
    recipient: merchantWallet,
    fromTimestamp: Math.floor(startOfDay.getTime() / 1000),
    toTimestamp:   Math.floor(endOfDay.getTime() / 1000),
    limit: 100,
  });

  const totalReceived = result.events.reduce(
    (sum, e) => sum + BigInt(e.amount), 0n
  );
  const totalFees = result.events.reduce(
    (sum, e) => sum + BigInt(e.fee), 0n
  );

  console.log(`Settlements: ${result.events.length}`);
  console.log(`Total received: $${Number(totalReceived) / 1e6}`);
  console.log(`Total fees:     $${Number(totalFees) / 1e6}`);

  return result.events;
}

Real-time dashboard feed

import { ExplorerClient } from '@stablecoin-stack/explorer-sdk';

const client = new ExplorerClient({ baseUrl: 'https://explorer.stablecoinstack.org' });
await client.connect();

// Stream all settlements to the browser via Server-Sent Events
app.get('/settlement-feed', (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  res.setHeader('Cache-Control', 'no-cache');
  res.setHeader('Connection', 'keep-alive');

  const handler = (event: SettlementEvent) => {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
  };

  client.onSettlement(handler);

  req.on('close', () => {
    client.offSettlement(handler);
  });
});

Lightweight local matching engine

import { ExplorerClient } from '@stablecoin-stack/explorer-sdk';

const client = new ExplorerClient({ baseUrl: 'https://explorer.stablecoinstack.org' });

// Load historical settlements on startup
const history = await client.getEvents({ limit: 100 });
const orderBook = new Map(
  history.events.map(e => [e.orderReference, e])
);

// Apply new settlements in real time
await client.connect();
client.onSettlement((event) => {
  orderBook.set(event.orderReference, event);
  console.log(`Order ${event.orderReference} settled. Book size: ${orderBook.size}`);
});

Next steps