Regulatory Short Position Change Layer

An adapter-based regulatory data layer for publicly disclosed net short positions. It gives capital-markets data, risk, compliance and operations teams an auditable incremental feed from official sources — not investment advice or a trading signal.

What problem it solves

Regulators publish disclosures in different formats, with different disclosure thresholds, publication delays, and lifecycle rules. Downloading a file repeatedly tells a user what exists now, but not what materially changed.

This Actor maintains a per-task snapshot and emits structured events:

• NEW_POSITION — a newly disclosed position after the baseline run
• POSITION_INCREASED / POSITION_DECREASED
• POSITION_CLOSED — previously public, now absent from the current source snapshot
• SOURCE_CORRECTION — source metadata changed without a percentage change
• BASELINE_POSITION — present on the first run; deliberately not described as “new”

It also produces an integration contract around those events:

• position-change-event — versioned, de-duplication-friendly events with a monotonic eventId, eventFingerprint, snapshotId, sourceAsOfDate, provenance and previous/current values;
• source-health — one record per selected source with retrieval status, counts, source fingerprint and explicit errors;
• run-summary — operational totals and a transparent initial-baseline flag;
• LATEST_SOURCE_HEALTH, LATEST_SNAPSHOT_VERSION and LAST_RUN_SUMMARY — Key-Value records for API consumers.

EU core source coverage

Source	Jurisdiction	Access	Data semantics
Norway Finanstilsynet Short Sale Register	Norway	Official public API, NLOD 2.0	Current public significant net-short positions
AMF open data	France	Daily official CSV, Open Licence 2.0	Published significant net-short-position lifecycle history
AFM Net Short Positions	Netherlands	Official current CSV	Current public significant net-short positions
Bundesanzeiger Net Short Positions	Germany	Official session-backed CSV export	Current public net-short position register
Central Bank of Ireland Public Net Short Positions	Ireland	Official XLSX	Current public significant net-short positions
CNMV Posiciones Cortas	Spain	Official XLS	Current public net-short positions

The Actor does not merge figures from different jurisdictions into a cross-market ranking. Every position-change event preserves the source-specific source, jurisdiction, disclosure_type, effective_date and publication-date fields.

For every adapter, the Actor reads a public regulator or regulator-supervised register. Public availability is not a statement that all jurisdictions have the same re-use licence: downstream consumers remain responsible for their own market-data, attribution and re-use obligations.

Why integrate this Actor instead of building it internally

Downloading a regulator’s file once is straightforward. The engineering cost begins when a workflow needs to run reliably over time and when a regulator changes a file, a lifecycle rule, or a publication pattern.

If a team builds internally	This Actor provides now	Boundary of this MVP
Build and maintain a parser for each regulator	Six official-source adapters across the EU core	It does not claim universal EU or global coverage
Define how an initial import differs from a newly disclosed position	Explicit BASELINE_POSITION versus NEW_POSITION semantics	A baseline is not historical reconstruction
Store previous source state and compare it safely	Persistent per-stateKey snapshots and lifecycle classification	State is scoped to one Actor user and state key
Prevent an upstream outage from generating misleading closures	Per-source health records; failed sources retain their last known state	It cannot repair or validate an outage at the regulator
Invent a consumer contract and operational telemetry	Versioned event envelope, source fingerprints, run summary and API links	The consumer still owns retention, authorization and downstream business rules

The value is therefore not an inaccessible dataset. It is a small managed integration boundary: a normalised change feed with evidence of what was read, when it was read, and whether one source failed. That lets a DMP, OMS-adjacent workflow, risk-control process or data team integrate without first creating and operating this plumbing.

It is deliberately a focused MVP, not a claim of an enterprise-grade SLA or universal market-data coverage. The durable product boundary is the common event contract and source-health model; future sources can be added as adapters without making cross-jurisdiction data appear comparable when it is not.

Where an official export contains multiple lifecycle rows for the same source, ISIN and position holder, the Actor selects the most recent dated observation before calculating state changes. receivedPositionCount reports raw adapter rows; trackedPositionCount reports the resulting distinct monitored positions.

Run it as a monitor

Use the same stateKey for every scheduled run. Its snapshot is held in an independent named Key-Value Store rather than the per-run default store. First run produces a transparent baseline; later runs emit incremental change events.

{
  "sources": ["norway", "france", "netherlands", "germany", "ireland", "spain"],
  "issuerKeywords": ["bank", "exchange", "financial"],
  "stateKey": "european-financial-sector-watch",
  "onlyChanges": true
}

Use isins when you need a strict instrument watchlist.

historyRetentionRuns controls how many snapshot-version metadata entries (default: 180) remain in the persistent store. Snapshot version metadata enables downstream consumers to identify the exact state used to create an event; it is not a substitute for an external regulatory archive.

Integration pattern

1. Schedule a Task with a stable stateKey.
2. Configure an Apify Task webhook for a successful run.
3. The consumer receives the run reference, reads the Dataset, and advances its own checkpoint using eventId or snapshotId. The event identifier is monotonic within a stateKey; consumers that persist deliveries can additionally de-duplicate by eventFingerprint.

Events are suitable for a DMP, risk/compliance workflow or operational queue. Consumers should retain source provenance and apply their own entitlement, retention and regulatory policies.

The Actor publishes machine-readable output links for the event stream, last run summary, latest snapshot version and source health. Its Dataset provides focused views for change events, source health and run summaries. See docs/API.md for response fields, run semantics and a checkpoint pattern.

Data quality and interpretation

• Public disclosure is regulated data, not a real-time feed.
• A position absent from a public snapshot may reflect a threshold/lifecycle rule, not necessarily an economic position of zero.
• French AMF explicitly cautions that a published sub-0.5% row can remain visible as the last public disclosure rather than the investor’s current economic position.
• The Actor reports source facts and changes; it does not infer short squeezes, price direction, manipulation, or a trading recommendation.
• POSITION_CLOSED means the record is absent from the selected source snapshot. It never asserts that an underlying economic position is zero.
• A FAILED source-health record is an operational result, not a clean source snapshot. The Actor deliberately keeps its preceding state so a failed request cannot create false POSITION_CLOSED events.

Development

pip install -r requirements.txt
pytest -q
python -m src.main

Set APIFY_LOCAL_STORAGE_DIR and provide an INPUT.json when running through the Apify local workflow.