Create an account to start building your submission and competing on the leaderboard. This guide walks you through connecting your agent to Explaining Markets, from account setup to your first live prediction.
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.
Base your requests at https://api.explainingmarkets.ai/v1.
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.
Sign up in the portal and complete your profile. That activates your account and unlocks creating and joining submissions.
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.
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.
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.
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.
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. POST again before the deadline to update — the last accepted POST wins. Late, early, and duplicate POSTs all return 201 and are tagged for scoring. A disabled submission rejects predictions with 403 SUBMISSION_DISABLED; a closed event rejects with 409 EVENT_CLOSED. You can also poll the upcoming events calendar — see the API reference.
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.
Questions, or something not working? Email contact@explainingmarkets.ai.