911stock

SEC EDGAR Integration

CIK Mapping

Always map tickers to 10-digit zero-padded CIK numbers:

const CIK_MAP: Record<string, string> = {
  SMCI: "0001096343",
  TSLA: "0001318605",
  NVDA: "0001045810",
}

To add a new ticker, look up the CIK at https://www.sec.gov/cgi-bin/browse-edgar?company=&CIK=TICKER&type=4.

Rate limiting

SEC EDGAR enforces a 5 requests/second limit. Always add 200ms delay between requests:

await delay(200) // before each EDGAR fetch

Form 4 parsing

Parse XML without external libraries using regex helpers:

function xmlTag(xml: string, tag: string): string {
  const re = new RegExp(`<${tag}[^>]*>[\\s\\S]*?</${tag}>`, "i")
  const m = re.exec(xml)
  return m ? m[1].trim() : ""
}

Key fields to extract:

• issuerTradingSymbol — ticker
• rptOwnerName — insider name
• officerTitle — role (CEO, CFO, etc.)
• transactionShares → value — share count
• transactionPricePerShare → value — price
• transactionAcquiredDisposedCode → value — "D" = sell, "A" = buy

10b5-1 detection

Check footnotes for "10b5-1" mentions. Scheduled sales are less suspicious:

const scheduled_10b5_1 =
  footnotes.includes("10b5-1") ||
  footnotes.includes("10b5\u20131") ||
  planCode === "1"

Signal Scoring

Score signals 0-10 using these factors:

Thresholds:

• Score < 5 → ignore, too low
• Score 5-6 → log and display, no call
• Score >= 7 → auto-trigger outbound phone call

Bland AI Voice Calls

Call script pattern

Always structure the call as:

1. Identify — "Hey, this is 911Stock."
2. Alert — Explain the signal with source citations
3. Offer action — "I can reduce your position by 50%."
4. Handle response — Use request_approval tool on "yes"
5. Reassure — "I'll keep monitoring" on "no"

const result = await makeOutboundCall(phone, explanation, signal)

Webhook flow

When user approves during the call:

1. Bland AI calls POST /api/bland-webhook with approval data
2. Webhook initiates Auth0 CIBA backchannel request
3. User gets push notification on Auth0 Guardian app
4. On Guardian approval → execute trade via /api/execute-trade

Auth0 CIBA Flow

Client-Initiated Backchannel Authentication enables push-based trade approvals:

1. Backend sends CIBA request to Auth0 with user's sub
2. Auth0 pushes notification to Guardian mobile app
3. User approves/denies on their phone
4. Backend polls POST /api/ciba-status for result
5. On approval → execute the trade

Always set AUTH0_AUDIENCE (defaults to "911stock-api").

Database Schema

Two tables, auto-migrated via GET /api/migrate:

CREATE TABLE IF NOT EXISTS signals (
  id TEXT PRIMARY KEY,
  ticker TEXT NOT NULL,
  company_name TEXT,
  insider TEXT,
  role TEXT,
  action TEXT,
  shares NUMERIC,
  price_per_share NUMERIC,
  total_value NUMERIC,
  date TEXT,
  filed_at TEXT,
  scheduled_10b5_1 BOOLEAN DEFAULT FALSE,
  last_transaction_months_ago NUMERIC,
  position_reduced_pct NUMERIC,
  score INTEGER,
  explanation TEXT,
  alerted BOOLEAN DEFAULT FALSE,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

CREATE TABLE IF NOT EXISTS alerts (
  id TEXT PRIMARY KEY,
  signal_id TEXT REFERENCES signals(id),
  ticker TEXT NOT NULL,
  call_id TEXT,
  explanation TEXT,
  approved BOOLEAN,
  created_at TIMESTAMPTZ DEFAULT NOW()
);

Use ON CONFLICT DO NOTHING when inserting signals to handle duplicate polling.

Real-Time Polling

The /api/poll endpoint is the heartbeat. Hit it on an interval:

// Client-side polling every 60 seconds
setInterval(() => fetch('/api/poll', { method: 'POST' }), 60_000)

Or configure Vercel Cron in vercel.json:

{
  "crons": [{ "path": "/api/poll", "schedule": "* * * * *" }]
}

The poll endpoint:

1. Fetches EDGAR for all watchlist tickers
2. Skips if score < 5
3. Deduplicates against DB
4. Auto-calls if score >= 7 and not already alerted

Stock Quotes

Fetch live prices from Yahoo Finance with 60-second caching:

// GET /api/stock-quote?symbol=SMCI
const url = `https://query1.finance.yahoo.com/v8/finance/chart/${symbol}`

Common Mistakes

• Don't skip the 200ms delay between EDGAR requests — SEC will rate-limit you
• Don't call Bland AI without checking alerted flag — you'll double-call users
• Don't use SELECT * on the signals table in production — use indexed ticker lookups
• Don't store phone numbers in client-side code — use env vars
• Always handle EDGAR XML parsing failures gracefully — filings vary in structure
• Never trust raw EDGAR data for trade execution — always run through Gemini analysis first

API Endpoints Reference