Skip to Content
Draft v0.2 — this specification is under active design and may change before implementation.
Resolver APIEndpoints you implement

Endpoints you implement

All endpoints live under your registered baseUrl. Every request except GET /health is signed with your callbackSecret:

X-Melee-Resolver-Id: <resolverId> X-Melee-Key-Id: <keyId of the callbackSecret used> X-Melee-Delivery-Id: <uuid, stable across retries of the same delivery> X-Melee-Timestamp: <unix millis, decimal> X-Melee-Signature: <hex lowercase HMAC-SHA256>

The signing string is "{METHOD} {path} {sha256hex(body)} {resolverId} {timestampMillis}" where path is the full URL path as requested (the path part of baseUrl plus the endpoint path, no host, plus ?query if any). Byte-exact rules and worked examples are in the Integration reference. Reject requests whose timestamp is more than 5 minutes from your clock in either direction, or whose signature does not verify against the secret named by X-Melee-Key-Id. During a secret rotation both the old and new keyId are valid for one hour.

PathPurposeYour response
POST /evaluateMarket acceptance step 1200 { confidenceBps, proposedDefinition?, notes? }
POST /acceptacceptance step 3200 { accepted, definitionHash, signature } or 200 { accepted: false, reason }
POST /liveacceptance step 4200 { acknowledged, definitionHash } or 200 { acknowledged: false, reason }
POST /cancelledproposal abandoned or creation failed2xx
POST /changea change to accept or reject, or a live RulesRequest200 { accepted, definitionHash, signature, reason? } or 202 (empty body) for RulesRequest
POST /applieda change you accepted has landed (or failed)200 { acknowledged, definitionHash }
POST /lifecyclelifecycle notifications2xx
POST /triggertrigger callback (below)2xx within 10 s
GET /status/{marketPubkey}status (below)200 status object, or 404 { "code": "unknown_market" } for markets you do not know
GET /healthhealth (below), unsigned200 { ok: true, version }

Two kinds of calls

Decisions — evaluate, accept, change (except RulesRequest). Synchronous; you must answer within the handshake timeout (30 s default, 120 s maximum). A timeout, a non-2xx, or a malformed body is a refusal and is not retried; the creator sees the outcome.

Notifications — live, applied, cancelled, lifecycle, trigger, RulesRequest. Delivered at least once with the same X-Melee-Delivery-Id; retried with exponential backoff for 24 hours until you return 2xx (for live and applied, until you return an acknowledgement body). Deduplicate on the delivery id. Deliveries can arrive out of order; order lifecycle events by slot, and treat any payload’s definitionVersion as authoritative over an older one. The delivery id always travels in X-Melee-Delivery-Id; only the lifecycle and trigger bodies also repeat it as deliveryId.

What to return on errors

SituationReturn
Signature or timestamp invalid401, body optional
Unknown proposalId or marketPubkey on a decision call200 { accepted: false, reason: "unknown" } (or 404, which we treat as refusal)
Unknown market on GET /status404 with body { "code": "unknown_market" }
Internal failure5xx; decisions are refused, notifications are retried

Bodies may be application/problem+json; we do not act on them.

Trigger callback

POST {baseUrl}/trigger

Sent at endDate + offsetSecs (EndTime) or whenever the creator requests resolution (Creator; may repeat). The same object is returned by GET /markets/{market}/status, where triggerType is null and sentAt is the response time.

{ "deliveryId": "1c3f…", "resolverId": "…", "bindingId": "…", "marketPubkey": "9xQe…", "marketId": "184", "title": "Will X happen by June 30?", "description": "…", "rules": "…", "marketToken": "EPjF…", "outcomes": [ { "index": 0, "pubkey": "…", "label": "Yes", "probabilityBps": 6120, "likelihoodBps": 5880 }, { "index": 1, "pubkey": "…", "label": "No", "unavailableReason": "market_not_active" } ], "endDate": 1788998400, "earliestProposalTs": 1788000000, "timeoutTs": 1789084800, "disputable": true, "triggerType": "EndTime", "definitionVersion": 3, "definitionHash": "9f2a…", "onChain": { "state": "Live", "numOutcomes": 2, "outcomePubkeys": ["…", "…"], "outcomeSetHash": "c41d…", "authorities": { "resolverAuthority": "…", "proposerAuthority": "…" }, "programId": "…" }, "currentProposal": { "outcomeIndex": 0, "isVoid": false, "proposedAt": 1788999000, "proposer": "…" }, "sentAt": 1788998401 }
  • bindingId identifies the pairing of your resolver with this market; it is stable for the market’s life.
  • probabilityBps and likelihoodBps are basis points out of 10,000: the probability implied by the minimum payout a winning share would receive, and the money-weighted event likelihood. When odds are not meaningful for an outcome both fields are omitted and unavailableReason is one of market_not_active, presale_book_frozen, no_liquidity, unknown.
  • definitionVersion and definitionHash identify the rules text this payload reflects. Compare with what you accepted before acting; see Verifying the definition.
  • onChain.state is one of Initialized, Pending, Presale, Live, Arbitration, Resolved, Failed, Cancelled, Closed, Voided.
  • earliestProposalTs is when the resolution window opens: 10 minutes after the market’s planned trading start, or later on the current program (see Contract versions). timeoutTs is the earliest Melee’s void authority may act. currentProposal is present only while a proposal stands.

Status

GET {baseUrl}/status/{marketPubkey}

{ "status": "Resolving", "message": "Awaiting official scores. Expected within 2 hours.", "updatedAt": 1788998700 }

status is one of Pending, Resolving, Dispute, Resolved. message is shown to users verbatim (≤ 280 characters). updatedAt is when your view last changed. Return 404 with the body { "code": "unknown_market" } for markets you do not know, including the activation probe market.

Poll schedule per market phase:

PhaseInterval
Live, before endDate + offsetSecsevery 30 minutes
Live, after endDate + offsetSecsevery 5 minutes
Proposal standingevery 1 minute
Before launch, or terminalnot polled

A 404 for a market you accepted, a 5xx, a timeout, a malformed body or an unknown status value all count as invalid; invalid past timeoutTs displays to traders as Unknown. Melee does not void a market for it.

Health

GET {baseUrl}/health — unsigned, so it can be served by ordinary infrastructure.

{ "ok": true, "version": "1.4.2" }

200 with ok: true within 10 seconds means healthy. Anything else counts toward Unhealthy. Melee’s callback source addresses are listed by GET /platform/callback-sources if you need to allowlist them.

How your status is displayed

Market phaseYour statusDisplayed
Accepted, not yet launchednot polledPending
Live, before earliestProposalTsanyPending
Live, before timeoutTsPending or invalidPending
LiveResolvingResolving
Live, after timeoutTsinvalidUnknown
Proposal standingPending or ResolvingResolving
Proposal standingDispute (disputable resolvers only)Dispute
Cancelled / Failed before launchnot polledCancelled / Failed
Resolved / VoidedanyResolved / Voided

Your message is always shown. Reporting Resolved before the chain says so is ignored.

Last updated on