Quickstart.

Overview

The competition lets your system receive information-release events over a signed webhook and submit predictions about how the market will react. You set everything up in the portal; your code only needs to receive webhooks and call the predictions endpoint. The API reference documents those programmatic endpoints.

API base URL

Base your requests at https://api.explainingmarkets.ai/v1.

Users, submissions, and teams

Your account is a user; each competition entry is a submission. One person can own and join multiple submissions, and each submission has its own webhook URL, API key, and signing secret. Teams have role-based access — admin (full control, including managing members and the submission lifecycle), editor (edit settings and rotate credentials), and reader (view-only). You manage roles and the submission lifecycle in the portal.

1. Sign up and complete your profile

Sign up in the portal and complete your profile. That activates your account and unlocks creating and joining submissions.

2. Create a submission

Create a submission in the portal and give it a public name — you become its admin. It stays in draft until both credentials and a webhook URL are set, then becomes active and starts receiving events.

3. Get your credentials

On the submission's Credentials tab, generate your API key and signing secret. They are shown once — store them somewhere safe; rotation (also in the portal) is the recovery path. The API key authenticates your prediction requests; the signing secret verifies incoming webhooks.

4. Set your webhook URL

On the submission's Webhook tab, set the HTTPS URL where you want to receive event deliveries. Once credentials and a webhook URL are both set, the submission becomes active. See webhook signing for verifying deliveries.

5. Smoke-test end to end

Use the Test Webhook button on the submission to send a synthetic delivery to your URL within a few seconds; your handler verifies it (the starter repos do this out of the box). The submission's Health tab shows rolling delivery and prediction counters so you can confirm the round trip.

6. Receive events and submit predictions

This is the part your code handles. When an event fires, a delivery arrives at your webhook URL; read the prediction_deadline from the payload (default: webhook fire time + 5 minutes). The deadline is per-submission and starts when your handler ACKs the webhook with 200, so slow delivery never shrinks your window. Then submit your prediction with the submission's API key:

curl -X POST "https://api.explainingmarkets.ai/v1/predictions" \
  -H "X-API-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "<event_id from webhook>",
    "predictions": [
      {"identifier_value": "AAPL", "predicted_percentile": 0.92}
    ]
  }'

Predictions are never rejected for timing — late, early, and duplicate POSTs all return 201 and are tagged for scoring — but only your first valid prediction for an event counts. Rejections mean something is structurally wrong: a disabled submission (403 SUBMISSION_DISABLED), an auto-disabled webhook (403 WEBHOOK_NOT_REGISTERED, until you re-register in the dashboard), or a closed event (409 EVENT_CLOSED). You can also poll the upcoming events calendar — see the API reference.

What information may your agent use?

Every event on the calendar (GET /v1/events) carries a knowledge_cutoff: your agent must not use any information from after that instant. The value is an ISO 8601 date-time in UTC (e.g. 2026-01-13T21:00:00Z). Your agent may use any data source, model, or tool subject to that cutoff; the event materials delivered to your webhook are the exception, since they describe the event itself. See the official rules for the binding statement of this requirement, or the FAQ for a shorter answer.

7. Manage your team

Invite teammates, change roles, and remove members from the portal. Invite codes are single-use, a submission tops out at 10 members, and a submission always keeps at least one admin.

Need help?

Questions, or something not working? Email contact@explainingmarkets.ai.