Quickstart

Get started with the Events API.

Prerequisites

• A modern browser or Node.js environment
• Basic familiarity with Server-Sent Events (SSE)

Connect to the Stream

Browser

const eventSource = new EventSource('https://events.matchstick.trading/api/stream');

eventSource.addEventListener('message', (event) => {
  const data = JSON.parse(event.data);
  console.log('Event:', data.eventType, data.issuer);
});

eventSource.addEventListener('error', (event) => {
  console.log('Connection state:', eventSource.readyState);
});

Node.js

Using the eventsource package:

npm install eventsource

import EventSource from 'eventsource';

const eventSource = new EventSource('https://events.matchstick.trading/api/stream');

eventSource.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log('Event received:', data);
};

Event Structure

All events follow the canonical Matchstick Event schema:

{
  "eventType": "FORM_4",
  "issuer": "APPLE INC",
  "cik": "0000320193",
  "filedAt": "2025-01-15T14:30:00Z",
  "confidence": 0.95,
  "metadata": {
    "reportingOwner": "Tim Cook",
    "transactionCode": "S",
    "shares": 10000,
    "pricePerShare": 185.50
  }
}

Filter Events

Filter the stream by event type:

// Only receive Form 4 trades
const source = new EventSource('/api/stream?types=FORM_4');

// Multiple types
const source = new EventSource('/api/stream?types=FORM_4,FILING_8K');

Local Development

To run the Events app locally:

# Clone the repo
git clone https://github.com/matchstick-trading/matchstick-events-apps.git
cd matchstick-events-apps

# Install dependencies
pnpm install

# Start development server
pnpm dev

Open http://localhost:5280 to view the app.

Next Steps

• Event Types - Full list of supported events
• Client Integration - React, Vue, Node.js examples
• API Reference - Complete endpoint documentation