# ASX Short Position Report API

> Daily processed ASIC short-selling data for the Australian market: full snapshot, deterministic risk scores, 60-day percentiles, sector/market-cap enrichment, and an AI narrative + structured risk assessment per flagged stock.

## Overview

This API turns the official (public) ASIC short-selling registry into a ready-to-use feed for trading bots and agents. It does the processing for you: anomaly flagging, composite risk scoring, historical percentile ranking, market-cap / squeeze-probability enrichment, and a daily AI-written market summary plus structured per-ticker assessment.

- Data source: Official ASIC Short Positions Registry (public data, T+4 reporting lag).
- Access: free, no authentication required.
- Base URL: https://asic-short-position-processor.flare-oracle.workers.dev

## Key endpoints

- GET /api/v1/openapi.json — Machine-readable OpenAPI 3.1 contract.
- GET /llms.txt — This file.
- GET /api/v1/asic/latest — Latest full report: market_data, anomaly_matrix, risk_narrative, risk_assessment.
- GET /api/v1/asic/dates — All archived report dates, newest first (free).
- GET /api/v1/asic/status — Service status: data freshness, next scheduled run, archive count (free, no auth).
- GET /api/v1/asic/latest/narrative — Latest AI market summary as plain text.
- GET /api/v1/asic/latest/assessment — Latest structured per-ticker assessment.
- GET /api/v1/asic/report/{date} — Archived full report for a date, YYYY-MM-DD.
- GET /api/v1/asic/report/{date}/narrative — Archived narrative.
- GET /api/v1/asic/report/{date}/assessment — Archived assessment.
- GET /api/v1/asic/squeeze-candidates?min_cover=3&confirmed=false&limit=20 — Ranked squeeze candidates: anomaly_matrix filtered by days_to_cover (Story 1 price/volume join), sorted by borrow_pressure then risk_score. Add `catalyst=true` for CATALYST_PRESENT rows only (Story 2 announcement join). Add `holder=true` for HOLDER_NOTICE rows only (Story 4 substantial-holder/director notices ±3d). Add `signal=squeeze_watch&min_conviction=30` for Story 3 composite-signal rows only.

## MCP (Model Context Protocol) — Streamable HTTP

- POST /mcp — Streamable HTTP endpoint, protocol `2025-03-26`, stateless (each POST creates a fresh server). Requires `Host` header, `Content-Type: application/json`, `Accept: application/json, text/event-stream`. `GET /mcp` returns 405.
- Discovery: `GET /.well-known/mcp.json` (also `/.well-known/mcp`) — `{ endpoint, transport, version, tools }`. Advertised via `Link: rel=mcp-server` and `rel=mcp-discovery`.
- Tools (10, all use `Host` header; historical variants require `date: YYYY-MM-DD`):
  - `get_latest_report` — full latest report (market_data, anomaly_matrix, risk_narrative, risk_assessment).
  - `get_latest_narrative` — latest AI narrative as plain text.
  - `get_latest_assessment` — latest structured per-ticker risk assessment.
  - `get_historical_report` — archived full report for `date`.
  - `get_historical_narrative` — archived narrative for `date`.
  - `get_historical_assessment` — archived assessment for `date`.
  - `list_available_dates` — all archived dates, newest first.
  - `get_service_status` — health/freshness (`kv_data_ready`, `last_asic_reporting_date`, `archived_report_count`).
  - `get_ticker_history` — per-ticker time series `asx_code` (e.g. `DRO`) + `limit` 1-60 (default 20, newest first, scans R2 `daily/*.json`; includes `price_close`, `volume`, `days_to_cover` where the Story 1 price join hit).
  - `get_squeeze_candidates` — top squeeze candidates from the latest report: `min_cover` (default 3), `confirmed_only`, `catalyst_only`, `holder_only` (Story 4 HOLDER_NOTICE), `signal` (squeeze_watch|accumulation_watch|event_driven_watch|quiet), `min_conviction` 0-100 (default 0), `limit` 1-50 (default 20).
- Example:
  ```bash
  # initialize
  curl -X POST https://asic-short-position-processor.flare-oracle.workers.dev/mcp \
    -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}'
  # tools/list then tools/call
  curl -X POST https://asic-short-position-processor.flare-oracle.workers.dev/mcp \
    -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" \
    -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_latest_narrative","arguments":{}}}'
  ```
- Notes: MCP reads KV/R2 directly (no x402 hop); REST `/api/v1/asic/*` remains x402-gated. Inspector: `npx @modelcontextprotocol/inspector --url https://asic-short-position-processor.flare-oracle.workers.dev/mcp`.

## Agent discovery suite

This API publishes the full agent discovery suite. All discovery surfaces are free, unauthenticated, and always-on:

- GET /agents.json — Typed action manifest for web agents (each action declares endpoint, parameters and x402 USDC price).
- GET /.well-known/agent-card.json — A2A AgentCard for agent-to-agent discovery.
- GET /.well-known/agent-skills/index.json — Agent Skills discovery index (agentskills.io v0.2.0) for the `asx-short-report` skill (also at /.well-known/agent-skills/asx-short-report/SKILL.md).
- GET /.well-known/x402 (also /.well-known/x402.json) — x402 payment discovery file (route pricing, network eip155:8453, input/output schemas).
- GET /.well-known/mcp.json (also /.well-known/mcp) — MCP discovery file (endpoint, transport, version, tools).
- GET /.well-known/security.txt — RFC 9116 security contact.
- GET /robots.txt — Robots + sitemap pointer; lists `/llms.txt` and `/llms-full.txt`.
- GET /sitemap.xml — Enumerates all discovery URLs + API contract.
- The RFC 8288 Link header on every response advertises all of the above.

## Pricing (x402 / USDC on Base)

| Route | Price |
|-------|-------|
| GET /api/v1/asic/latest | $0.005 |
| GET /api/v1/asic/squeeze-candidates | $0.005 |
| GET /api/v1/asic/latest/assessment | $0.003 |
| GET /api/v1/asic/report/{date} | $0.003 |
| GET /api/v1/asic/latest/narrative | $0.001 |
| GET /api/v1/asic/report/{date}/assessment | $0.002 |
| GET /api/v1/asic/report/{date}/narrative | $0.001 |

## Data model

- Anomaly: asx_code, short_interest_pct, prior_day_pct, delta_pct, consecutive_rising_days, anomaly_type (HIGH_SHORT_SQUEEZE_RISK | RAPID_ACCUMULATION | SUSTAINED_ACCUMULATION | HARD_TO_BORROW | VOLUME_CONFIRMED | SHORTS_UP_PRICE_HOLDING | CATALYST_PRESENT | RESULTS_WEEK | CAP_RAISE_OVERHANG | HOLDER_NOTICE | HOLDER_CUSTODIAL | BORROWED_HOLDING | HOLDER_RETURN), risk_score (0-100), history_percentile_60d, sector, industry, market_cap, price_aud, squeeze_probability, price_close, volume_today, avg_vol_20d, days_to_cover, volume_spike_ratio, price_5d_pct, divergence_flag, borrow_pressure, price_as_of, price_stale, catalyst_count_3d, catalyst_headlines, results_week, cap_raise_overhang, holder_count_3d, holder_headlines, holder_present (Story 4 substantial-holder/director subset, metadata only — direction unknown, independent of priceSensitive), holder_custodial (Story 4 P0a: notice names a known agent-lender/prime broker — borrowed/client stock possible, not a beneficial long), holder_nature (Story 6 parsed PDF direction: beneficial|borrowed|custodial|mixed|unknown, null when no parse — overrides the headline heuristic), borrowed_pct (borrowed % stated in notice, null when absent), offsetting_short_pct (Dec-2026+ form field, first observed short number, null when unstated), signal (squeeze_watch|accumulation_watch|event_driven_watch|quiet — Story 3 composite, positioning-heavy 40/30/15/15, >=2 pillars), signal_conviction (0-100), signal_confidence (high|medium|low), signal_drivers (cite only these). Price/volume fields are null with `price_stale: true` when the Yahoo join missed that run; `catalyst_count_3d: 0` (never null) means no ASX announcements in the ±3d window; risk numbers are unaffected. `price_as_of` may differ from `asic_reporting_date` (T+4 shorts vs T+0 prices).
- RiskAssessmentEntry: asx_code, severity (LOW|MEDIUM|HIGH), direction (accumulating|declining|stable), status (new|continuing), summary (<=20 words).
- Clean days return an empty assessment and the narrative "No anomalies flagged today."

## Documentation

- OpenAPI: https://asic-short-position-processor.flare-oracle.workers.dev/api/v1/openapi.json
- Response headers include `X-Data-Source: Official ASIC Short Positions Registry`.