Returning.AIDevelopers
v1

API reference / Gamification / Match Predictions

.md

Settle match prediction

Send a match's final score to start paying rewards to the traders who predicted it correctly.

Last updated 26 Sep 2026API v1

Method
POST
Path
https://api.returning.ai/v1/match-predictions/{matchPredictionId}/settlements
Permission
matchPredictions
Retries
Idempotency-Key required; same key and body replays

When to use this

  • The match has finished and your results feed has the final score.
  • An earlier settlement failed and you need to run it again.

Authentication#

Header
Authorization: Bearer <API_KEY>
Permission
matchPredictionsShown in the dashboard as “Match Prediction”

Use a Community API key with matchPredictions, shown in the dashboard as Match Prediction, and keep it on your server. The key decides the community: you only see and change match predictions in that community, and an ID from another community returns 404, the same as an unknown ID. Personal API keys are rejected with 403.

Behaviour#

api.returning.ai doesn't serve this route yet: requests return an empty 404. Ask Returning.AI before you build on it.

Settlement runs in the background: a 202 means it has started, not finished. Poll Get settlement results until it returns 200. While it runs, the match shows settlement_in_progress.

You can settle once kickoffAt has passed, and only a published match that isn't already settled, voided or being voided. A match whose settlement failed can be settled again.

Each prediction is scored against the score you send:

  • Right result (team A win, team B win or draw), wrong score: rewards.correctResult.
  • Right result and exact score: rewards.correctResult plus rewards.exactScoreBonus.
  • Wrong result: nothing.

Winners also get their entry cost back, added to their coin payout. Settlement also sends your community's match prediction webhooks, if you have set any up.

Request#

Path parameters#

matchPredictionId#stringREQUIRED
The match prediction ID from Create match prediction or List match predictions.

Rulemp_ and 24 hex characters

Eg"mp_66f000000000000000000801"

Headers#

Authorization#stringREQUIRED
Community API key with matchPredictions.

RuleBearer <API_KEY>

Idempotency-Key#stringREQUIRED
A unique key you create for this settlement, such as a UUID. Reuse it only to retry the same body.

Rule1-255 characters

Eg"3f9c2a7e-1b4d-4e8a-9c61-2d5f7a8b9e10"

Content-Type#stringREQUIRED
Request body format. Anything else returns 415.

Ruleapplication/json

X-Request-Id#stringOPTIONAL
Your own ID for this request, returned in meta.requestId. Without it, a req_... ID is generated.

Body#

fullTimeScore#objectREQUIRED
The final score to settle on. It is used as sent, whatever scoreBasis says.

Eg{"teamA": 2, "teamB": 1}

teamA#integerREQUIRED
Team A's goals.

RuleWhole number, 0 or more

Eg2

teamB#integerREQUIRED
Team B's goals.

RuleWhole number, 0 or more

Eg1

curl --request POST \
  --url https://api.returning.ai/v1/match-predictions/mp_66f000000000000000000801/settlements \
  --header 'Authorization: Bearer <API_KEY>' \
  --header 'Idempotency-Key: 3f9c2a7e-1b4d-4e8a-9c61-2d5f7a8b9e10' \
  --header 'Content-Type: application/json' \
  --data '{
    "fullTimeScore": {
      "teamA": 2,
      "teamB": 1
    }
  }'

Response#

A 202 returns the settlement's operationId and the resultsUrl to poll. If a settlement is already running on this match under a different key, you get 202 MATCH_PREDICTION_SETTLEMENT_IN_PROGRESS with the running settlement's details instead; poll its results rather than starting another.

meta#objectALWAYS
Result details.
status#stringALWAYS
Result of the request.

Rulesuccess

statusCode#integerALWAYS
The HTTP status, repeated.
code#stringALWAYS
Machine-readable result code.

RuleMATCH_PREDICTION_SETTLEMENT_ACCEPTED, or MATCH_PREDICTION_SETTLEMENT_IN_PROGRESS when a settlement is already running

requestId#stringALWAYS
Your X-Request-Id if you sent one, otherwise a generated req_... ID. Quote it when you contact support.
message#stringALWAYS
Human-readable summary. Do not branch on it.
data#objectALWAYS
The settlement that was started.
operationId#stringALWAYS
The settlement ID.

Rulemps_ and 32 hex characters

type#stringALWAYS
Always settlement.
status#stringALWAYS
settlement_in_progress when it starts. A replay shows the status the settlement had then.
submittedAt#stringALWAYS
When the settlement was accepted.
resultsUrl#stringALWAYS
Where to poll for the outcome, without the host.
{
  "meta": {
    "status": "success",
    "statusCode": 202,
    "code": "MATCH_PREDICTION_SETTLEMENT_ACCEPTED",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Match prediction settlement accepted.",
  "data": {
    "operationId": "mps_66f00000000000000000000000000803",
    "type": "settlement",
    "status": "settlement_in_progress",
    "submittedAt": "2026-10-10T21:00:00.000Z",
    "resultsUrl": "/v1/match-predictions/mp_66f000000000000000000801/results"
  }
}

Errors#

Every error carries its code in meta.code and the request's ID in meta.requestId. Validation errors list each problem in details, with a field, code and message. The API key checks (401, 403, 404 COMMUNITY_NOT_FOUND and 500 AUTHENTICATION_FAILED) return detail and solution instead. A 404 with an empty body means the route isn't available on api.returning.ai yet. A 400 or 409 changes nothing.

Fix the request10

404Fix the request
The body is empty: api.returning.ai doesn't serve this route yet. Ask Returning.AI before you build on it.
400MATCH_PREDICTION_VALIDATION_FAILEDFix the request
fullTimeScore is missing, a score isn't a whole number of 0 or more, or the body has another field. details names it. Nothing changed.
400READ_ONLY_FIELDFix the request
The request has a field the server sets, such as status or settlement. details names it. Remove it.
400INVALID_JSONFix the request
The body is not valid JSON. Fix the syntax and send it again.
400IDEMPOTENCY_KEY_REQUIREDFix the request
Send an Idempotency-Key header with a unique value.
400IDEMPOTENCY_KEY_INVALIDFix the request
The Idempotency-Key is longer than 255 characters. Use a shorter key, such as a UUID.
415UNSUPPORTED_MEDIA_TYPEFix the request
Send the body as JSON with Content-Type: application/json.
401AUTHENTICATION_REQUIREDFix the request
The key is missing, invalid or expired. Send Authorization: Bearer <API_KEY> with a current Community API key.
403API_KEY_PERMISSION_DENIEDFix the request
The key lacks matchPredictions, or it is a personal key. Use a Community API key and add Match Prediction in Settings > Integration > API Keys.
409IDEMPOTENCY_KEY_CONFLICTFix the request
This Idempotency-Key was already used with a different body. Use a new key for a new body.

Fix the data05

404MATCH_PREDICTION_NOT_FOUNDFix the data
No match prediction in your community has this ID. Check it is the full mp_... ID from Create match prediction or List match predictions.
404COMMUNITY_NOT_FOUNDFix the data
The community this key belongs to no longer exists. Contact Returning.AI support.
409MATCH_NOT_STARTEDFix the data
kickoffAt hasn't passed yet. Settle after kickoff, or move kickoffAt with Patch match prediction if the match started early.
409INVALID_LIFECYCLE_TRANSITIONFix the data
The match is a draft, or already settled or voided. Only a published match that isn't finished can be settled. Nothing changed.
409OPERATION_IN_PROGRESSFix the data
A void is running on this match, so it can't be settled. Check the outcome with Get settlement results.

Retry with backoff05

429RATE_LIMITEDRetry with backoff
Your community is over its rate limit. Wait for the seconds in Retry-After, then retry.
500INTERNAL_ERRORRetry with backoff
The outcome is unclear. Check Get settlement results before you send the settlement again with a new key.
500AUTHENTICATION_FAILEDRetry with backoff
The key could not be checked. Retry with backoff; nothing changed.
503SETTLEMENT_QUEUE_UNAVAILABLERetry with backoff
Settlement couldn't be started, and nothing changed. Retry later with a new Idempotency-Key: the same key returns this 503 again.
503MATCH_PREDICTION_FROZENRetry with backoff
Returning.AI has paused match prediction requests. Nothing changed. Retry later with backoff.
{
  "meta": {
    "status": "error",
    "statusCode": 404,
    "code": "MATCH_PREDICTION_NOT_FOUND",
    "requestId": "req_66f00000000000000000000000000811"
  },
  "message": "Match prediction not found."
}

Next step#

Get settlement resultsGET/v1/match-predictions/{matchPredictionId}/resultsPoll until the settlement finishes, then read the totals and each trader's payout.