# 3P Signals — DRM3 Third-Party Data Aggregator
# Base URL: https://signals.data.drm3.network
# 20 external data sources. Every fetch provenance-signed with Ed25519.

## Authentication

All /signals/v1/* endpoints require the X-Signals-Key header.
Demo key: sig3_demo_alpha_test

Example:
  curl -s "https://signals.data.drm3.network/signals/v1/sources" \
    -H "X-Signals-Key: sig3_demo_alpha_test"

Public endpoints (no key): /health, /llms.txt, /.well-known/signals-3p-keys.json

## Available Sources (use as :source parameter)

Financial: nasdaq, fdic, etherscan_labels
Government: congress, fed_register, fred, govinfo, gov_rss, census, sec_edgar
Environmental: open_meteo, usgs_earthquakes, usgs_water
Social: reddit, gdelt, github_activity
Prediction: polymarket
Web Intelligence: tranco, majestic, gsa_gov

## Endpoints

### GET /health
No auth required. Returns system status, source count, signal count.
Response: { status: "ok"|"degraded"|"error", sku, product, sources_active, signals_total, last_fetch }

### GET /signals/v1/sources
List all data sources with status and metrics.
Response: { sources: [{ id, name, category, cadence_seconds, is_active, last_fetched_at, fetch_count, error_count, avg_latency_ms, last_error }] }

### GET /signals/v1/sources/:source
Detail for one source. Replace :source with a source ID (e.g., congress, fred).
Response: { source: { id, name, category, ... }, latest_fetch: { fetched_at, entity_count, latency_ms } }

### GET /signals/v1/signals/:source
Paginated signal data for a source. This is the main data endpoint.
Parameters:
  ?page=1    (default 1)
  ?limit=100 (default 100, max 500)
Response: { signals: [{ entity_key, fetched_at, output_hash, ...source-specific columns }], page, limit, total }

Source-specific columns vary. Examples:
  congress: bill_id, title, origin_chamber, policy_area, latest_action_date
  fred: series_id, series_name, value, observation_date, units
  open_meteo: city, temperature_c, humidity_pct, wind_speed_kmh, precipitation_mm
  reddit: subreddit, title, score, num_comments, upvote_ratio
  polymarket: event_id, title, probability, volume_24h, volume_total
  usgs_earthquakes: magnitude, place, event_time, depth_km, tsunami_warning
  fed_register: document_number, title, doc_type, agencies, publication_date
  sec_edgar: accession_number, form_type, company_name, filed_date
  fdic: institution_name, total_assets, total_deposits, net_income
  census: variable_name, value, geo_name, year
  govinfo: collection, title, date_issued, government_author
  gdelt: title, url, domain, source_country, tone
  github_activity: repo_name, stars, forks, language, topics
  nasdaq: symbol, name, exchange, market_tier
  tranco: domain, rank, tier
  majestic: domain, rank, ref_subnets, ref_ips
  gsa_gov: domain, agency, organization, state
  usgs_water: site_name, parameter, value, unit
  etherscan_labels: address, nametag, labels, balance_eth

### GET /signals/v1/signals/:source/:entity_key
Latest signal for a specific entity. Entity keys are source-specific:
  congress: bill_id (e.g., hr-8404)
  fred: series_id (e.g., FEDFUNDS, DGS10)
  reddit: post_id
  polymarket: event_id
Response: { signal: { entity_key, fetched_at, ...columns } }

### GET /signals/v1/signals/:source/:entity_key/history
Historical values for one entity. Shows how data changed over time.
Parameters:
  ?page=1
  ?limit=50
Response: { history: [{ entity_key, fetched_at, ...columns }], page, limit }

### GET /signals/v1/sources/:source/fetch-log
Audit trail of every fetch for a source. Shows when data was collected.
Response: { fetches: [{ id, source, fetched_at, entity_count, latency_ms, output_hash, receipt_id, query_urls, query_description }] }

### GET /signals/v1/sources/:source/fetch/:id
Drill into a specific fetch. See exactly what entities were collected.
Parameters:
  ?page=1
  ?limit=100
Response: { fetch: { id, fetched_at, ... }, entities: [...], page, limit }

### GET /signals/v1/sources/:source/provenance
Ed25519 provenance receipt chain for a source. Cryptographic proof of data collection.
Response: { receipts: [{ id, source, fetched_at, output_hash, signature, receipt_json }] }

### GET /.well-known/signals-3p-keys.json
Public Ed25519 signing keys for verifying provenance receipts. No auth required.
Response: { keys: [{ source, public_key, derivation_path }] }

### GET /signals/v1/bq/status
BigQuery archive status.
Response: { enabled, project_id, dataset_id }

### POST /signals/v1/trigger-cron
Manually trigger the next scheduled fetch. Runs due sources immediately.
Response: { ok: true, message: "Cron triggered" }

## Usage Examples

# Get all sources
curl -s "https://signals.data.drm3.network/signals/v1/sources" -H "X-Signals-Key: sig3_demo_alpha_test"

# Get 10 recent congressional bills
curl -s "https://signals.data.drm3.network/signals/v1/signals/congress?limit=10" -H "X-Signals-Key: sig3_demo_alpha_test"

# Get FRED economic indicators
curl -s "https://signals.data.drm3.network/signals/v1/signals/fred?limit=15" -H "X-Signals-Key: sig3_demo_alpha_test"

# Get recent earthquakes
curl -s "https://signals.data.drm3.network/signals/v1/signals/usgs_earthquakes?limit=10" -H "X-Signals-Key: sig3_demo_alpha_test"

# Get prediction market events
curl -s "https://signals.data.drm3.network/signals/v1/signals/polymarket?limit=10" -H "X-Signals-Key: sig3_demo_alpha_test"

# Get Reddit hot posts
curl -s "https://signals.data.drm3.network/signals/v1/signals/reddit?limit=20" -H "X-Signals-Key: sig3_demo_alpha_test"

# Verify provenance chain for Congress data
curl -s "https://signals.data.drm3.network/signals/v1/sources/congress/provenance" -H "X-Signals-Key: sig3_demo_alpha_test"

## Rate Limits
100 requests per minute per IP.

## Data Freshness
Hourly: polymarket, open_meteo, congress, fred, govinfo, fed_register, reddit, usgs_earthquakes, usgs_water
Daily: nasdaq, sec_edgar, fdic, census, gdelt, github_activity, tranco, majestic, gsa_gov, etherscan_labels