# Explaining Markets Competition

> A live, out-of-sample benchmark and open quarterly competition measuring how well AI systems explain stock returns around earnings announcements. Participating systems receive earnings events on a signed webhook as they happen and submit predictions using any information available before the announcement plus the earnings-call transcript; predictions are scored against realized returns on a live leaderboard. Introduced in the working paper by Koijen and Levy, where the best-optimized agentic systems raise the explained variation in returns (R²) from ~8% to ~20%.

You build a "submission" that (1) receives HMAC-signed webhook deliveries when events fire and (2) POSTs predictions to the REST API. Accounts, submissions, credentials, and teams are managed in the web portal; your code only needs the webhook handler and the predictions call. Authenticate API calls with your submission's key in the `X-API-Key` header. API base URL: https://api.explainingmarkets.ai/v1

## Getting Started

- [Quickstart](/docs.md): End-to-end setup — accounts/submissions/teams, credentials, setting a webhook URL, submitting your first prediction (with a curl example).
- [Webhook signing](/docs/webhooks.md): Verifying deliveries — Standard Webhooks HMAC-SHA256 scheme, headers you receive, common mistakes, test vectors.
- [Webhook test vectors](/test_vectors.json): Frozen known-answer HMAC signatures (single-signature and rotation-overlap) to self-test your webhook verifier offline.
- [OpenAPI specification](/openapi.json): Machine-readable contract for the participant-facing endpoints (events calendar, predictions, historical archive, health, webhook self-test).
- [API reference](/docs/api): Human-readable rendering of the OpenAPI spec.

## Competition

- [Official rules](/contest-rules.md): The binding terms of the current quarter — eligibility, entry, the knowledge-cutoff requirement, scoring and imputation, prizes, winner verification, and governing law. Controls over any inconsistent description elsewhere.
- [Live leaderboard](/leaderboard): Current quarterly standings, including reference LLM baselines.
- [Demo portal](/demo): Read-only, no-login walkthrough of the participant portal — submissions, health, and prediction feedback rendered against sample data.
- [Working paper (SSRN)](https://papers.ssrn.com/sol3/papers.cfm?abstract_id=6474601): "Assessing the Benefits of Optimized Agentic AI Systems for Asset Pricing," Koijen and Levy.

## Quickstarts

- [starter-modal](https://github.com/explaining-markets/starter-modal): Working webhook handler + prediction client with a vendored signature verifier — get an agent running on Modal in under 5 minutes.
- [starter-railway](https://github.com/explaining-markets/starter-railway): The same quickstart, deployable on Railway.

## Baselines

- [baseline-earnings-summary](https://github.com/explaining-markets/baseline-earnings-summary): Reference baseline from Koijen and Levy — the earnings-call-summary system, run as an entry on the leaderboard.

## Optional

- [Full text export](/llms-full.txt): This roadmap plus the full docs and a compact endpoint listing, concatenated for single-fetch ingestion.
- [Newsletter](https://explainingmarkets.substack.com): Quarterly results, SDK releases, announcements.
- [X / @explainingmrkts](https://x.com/explainingmrkts): Updates.