DEVELOPER DOCUMENTATION · SETTLEMENT CONTRACT

Every outcome,
one receipt you can audit.

Six states. Every move is one verb. This page and openapi.yaml are the contract.

Settlement state machine with six states: open, locked, held, settled, reversed and voided. Open moves to locked or voided. Locked moves to held, settled or voided. Held is a waiting state and moves to settled or voided. Settled can be reversed. Reversed and voided are terminal. PLLAY settles from recorded match video.
Generated from TRANSITIONS · 8 edges · terminal: reversed, voided
HOW IT WORKS

Five stages.
One record.

Production base URLs are issued with access. A sandbox key works on the sandbox base URL provided with the key. The examples use $PLLAY_API for that URL. Tour fixture: the sandbox page runs in your browser, needs no key and does not call the hosted API. Create sends spec.game_slug and does not send threshold. spec.pov_side (home or away) is required for dota2 and rocketleague. Settle sends an empty body.

  1. 01Propose

    The partner submits a recorded clip: an https URL, the game adapter and the market to decide (POST /v1/vision/verify on the partner API). The partner then opens the event in the settlement contract. The partner keeps funds and KYC (and stake_ref, for operator contests only).

    Recorded-video verification is built and benchmarked. Which titles are available is on Status. The settlement contract below is separate and carries the decision.

    # Vision intake (partner API): submit the clip
    curl -X POST "$PLLAY_PARTNER_API/v1/vision/verify" -H "X-Partner-Key: $PARTNER_KEY" -H "Content-Type: application/json" \
      -d '{"video_url":"https://example.com/your-fortnite-clip.mp4","adapter":"fortnite_result.json","game_slug":"fortnite","market":{"kind":"pov","options":["WIN","LOSE"]},"external_market_id":"your-reference"}'
    # 202: verification_id and event_id returned, status "queued"
    
    # Settlement contract: open the event
    curl -X POST "$PLLAY_API/v1/events" -H "X-Partner-Key: $PARTNER_KEY" -H "Content-Type: application/json" \
      -H "Idempotency-Key: $UNIQUE_KEY" \
      -d '{"type":"promo","path":"vod","notional_minor":0,"spec":{"title":"Fortnite","question":"Did the POV player win (Victory Royale)?","game_slug":"fortnite"}}'
    # 201: state "open", event_id returned
  2. 02Verify

    Vision AI reads the recorded clip frame by frame and Oracle evaluates the readings against the rule. When confidence is at or above the event’s threshold, the event settles. It is held when the read is not clear or the evidence is insufficient, and if the clip is unreadable it voids. The settlement contract records the decision as a score against a threshold; the score is a model score, not the probability that the result is correct.

    Between propose and settle the event is locked.

    Hold = no settle. Not settled yet. Held is a waiting state, not an error: wait for event.settled or event.voided.

    curl -X POST "$PLLAY_API/v1/events/$EVENT_ID/lock" -H "X-Partner-Key: $PARTNER_KEY" -H "Content-Type: application/json"
    # 200: state "locked"
  3. 03Settle

    Six states: open, locked, then held, settled or voided; settled can be reversed. A settled result returns a settlement_id and an evidence_uri. A reversal is recorded as a new entry with its own id, and the original settlement_id is kept.

    Reverse = a new entry, not an edit.

    curl -X POST "$PLLAY_API/v1/events/$EVENT_ID/settle" -H "X-Partner-Key: $PARTNER_KEY" -H "Content-Type: application/json" \
      -d '{}'
    # 200. The server sets outcome, confidence and model_version.
    
    curl -X POST "$PLLAY_API/v1/events/$EVENT_ID/hold" -H "X-Partner-Key: $PARTNER_KEY" -H "Content-Type: application/json" \
      -d '{"reason":"below_threshold"}'
    # 200: state "held". Not settled yet.
  4. 04Contest

    A partner contests inside the window on /trust. Those times are the target process, not a guarantee. A reversal is a new entry with a reason, and the original settlement_id is kept.

    Contest per /trust.

    Dispute window on /trust →
    curl -X POST "$PLLAY_API/v1/events/$EVENT_ID/reverse" -H "X-Partner-Key: $PARTNER_KEY" -H "Content-Type: application/json"
    # 403 reversal_requires_dispute. Nothing is written. File a dispute at POST /v1/events/{id}/dispute.
  5. 05Live exception

    PLLAY settles from recorded match video. The settlement contract refuses a live settle that has no reviewer_id (422 live_unreviewed). Automated live-stream settlement is Phase 2.

What Vision can settle

Recorded video is built and benchmarked on these titles. PLLAY settles from recorded match video. Automated live-stream settlement is Phase 2. See all titles →

Beyond gaming concepts — labeled Concept until /status and /coverage say otherwise. See the showcase →

You keep funds, KYC, and media margins. PLLAY returns the settlement_id.

Worked example · a recorded creator challengeDid the creator’s clutch round finish under 30 seconds?
01 Propose
path=vod · the server sets the threshold
02 Verify
Vision reads the clip and confidence is at or above the event’s threshold, so it settles.
03 Settle
state settled
settlement_id
7f3ac91e-2b4d-4e60-8a15-c0d9e3f1a762
evidence_uri
https://pllay.io/receipt/5d0e8a14-3b7c-4f29-a6d1-9c2e47b0f385Example value · See the example receipt page

evidence_uri pattern: https://pllay.io/receipt/{event_id}

Sandbox showcase / Demo — not an authenticated production test until /status says so.

Which titles are available, and which settle automatically, is on Status →

settledpath=vod

Example question: did the creator’s clutch round finish under 30 seconds?

00:41.200 → 00:44.800frames read: 8

Settled

clip window
00:41.200 → 00:44.800
model_version
vision-vod-2026-09
reviewer_id
null · vod
settlement_id
7f3ac91e-2b4d-4e60-8a15-c0d9e3f1a762
evidence_uri
pattern: https://pllay.io/receipt/{event_id}Example value · See the example receipt page
pool
Pool clears through the partner. Clearance fee applies (settled only).

Sandbox receipt · illustrative

Which titles are available, and which settle automatically, is on Status →

What we are not: not a sportsbook, casino or prediction-market operator, and not a crypto oracle.

Sample receipt · illustrative

Result Player result: WIN

Evidence frame (illustrative): PLLAY Arena Dodge · original PLLAY title · scripted demo
Evidence frame (illustrative) · PLLAY Arena Dodge · original PLLAY title · scripted demo
settled

Settled automatically

A clear read settles automatically. This card is an illustration.

event_id
evt_sample
settlement_id
stl_sample_…
evidence_hash
sha256:<64 hex characters> (placeholder)
held

Held for review: unclear results are checked before they settle, so an unclear result is never settled on a guess.

The read was not clear enough to settle on its own, so it is checked before it settles.

event_id
evt_sample
settlement_id
null · held for review
evidence_hash
sha256:<64 hex characters> (placeholder)
TRANSITIONS
FromToVerb
openlockedPOST /v1/events/:id/lock
openvoidedPOST /v1/events/:id/void
lockedheldPOST /v1/events/:id/hold
lockedsettledPOST /v1/events/:id/settle
lockedvoidedPOST /v1/events/:id/void
heldsettledPOST /v1/events/:id/settle
heldvoidedPOST /v1/events/:id/void
settledreversedPOST /v1/events/:id/dispute
reversedterminal · no transitions
voidedterminal · no transitions
FIELDS
FieldTypeNotes
event_iduuidStable id across every state.
type'promo' | 'contest' | 'duel'Event type. Same machine for all three.
path'vod' | 'live'vod is recorded video. PLLAY settles from recorded match video.
stateEventStateopen | locked | held | settled | reversed | voided.
specobjectTitle, market and rule the outcome is judged against.
outcomestring | nullyes | no | void once settled. null until then, and while held.
confidencenumber 0–1 | nullModel score for the outcome. null until settled.
thresholdnumber 0–1settle rejected when confidence < threshold.
model_versionstring | nullExact model build that produced the call.
evidence_uriuri | nullFrames, signals and clip window bundle.
settlement_iduuid | nullOutcome record id. null until settled. Kept after a reversal.
reversal_settlement_iduuid | nullSet only when state is reversed: the id of the reversal. null otherwise.
reviewer_iduuid | nullA UUID when a person confirmed a result. PLLAY settles from recorded match video.
stake_refstring | nullOperator reference, for operator contests only. Leave it null on promo events (Pulse); the API does not check this.
notional_minorintegerPool or stake value in minor units. Basis for the clearance fee on settle.
reasonstring | nullSet by hold, void and reverse.

evidence_uri may point to a bundle that includes sources[] when corroboration is enabled for a title. That is designed, and no title has it yet. Optional receipt fields (receipt_hash, anchor_tx, anchor_status) are not part of this object and are not populated. Public hash anchor: Off. The code exists, no chain is configured and nothing is anchored.

RULES
1.held pays nobody.
2.reversed records a new entry with its own id; the original settlement_id is kept.
3.promo has no stake_ref.
4.contest and duel stake lives on the operator.
5.Clearance and usage fees accrue only when state=settled.
Contract

OpenAPI 3.1 · artifacts/settlement/openapi.yaml

Seven operations. No other verbs exist.

DevelopersRequest a key
State machine

Six states.
Eight moves.

Every moment runs the same machine. No state is skipped and no move is invented. A settle below threshold is refused. PLLAY settles from recorded match video.

openlockedheldsettledvoidedreversedheld = waiting state, not an errorlive: comingvod: confidence ≥ threshold
unclear read → held for review → settledrun 2 / 5 · illustrative