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.
| Path | Purpose | Your response |
|---|---|---|
POST /evaluate | Market acceptance step 1 | 200 { confidenceBps, proposedDefinition?, notes? } |
POST /accept | acceptance step 3 | 200 { accepted, definitionHash, signature } or 200 { accepted: false, reason } |
POST /live | acceptance step 4 | 200 { acknowledged, definitionHash } or 200 { acknowledged: false, reason } |
POST /cancelled | proposal abandoned or creation failed | 2xx |
POST /change | a change to accept or reject, or a live RulesRequest | 200 { accepted, definitionHash, signature, reason? } or 202 (empty body) for RulesRequest |
POST /applied | a change you accepted has landed (or failed) | 200 { acknowledged, definitionHash } |
POST /lifecycle | lifecycle notifications | 2xx |
POST /trigger | trigger 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 /health | health (below), unsigned | 200 { 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
| Situation | Return |
|---|---|
| Signature or timestamp invalid | 401, body optional |
Unknown proposalId or marketPubkey on a decision call | 200 { accepted: false, reason: "unknown" } (or 404, which we treat as refusal) |
Unknown market on GET /status | 404 with body { "code": "unknown_market" } |
| Internal failure | 5xx; 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
}bindingIdidentifies the pairing of your resolver with this market; it is stable for the market’s life.probabilityBpsandlikelihoodBpsare 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 andunavailableReasonis one ofmarket_not_active,presale_book_frozen,no_liquidity,unknown.definitionVersionanddefinitionHashidentify the rules text this payload reflects. Compare with what you accepted before acting; see Verifying the definition.onChain.stateis one ofInitialized,Pending,Presale,Live,Arbitration,Resolved,Failed,Cancelled,Closed,Voided.earliestProposalTsis when the resolution window opens: 10 minutes after the market’s planned trading start, or later on the current program (see Contract versions).timeoutTsis the earliest Melee’s void authority may act.currentProposalis 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:
| Phase | Interval |
|---|---|
Live, before endDate + offsetSecs | every 30 minutes |
Live, after endDate + offsetSecs | every 5 minutes |
| Proposal standing | every 1 minute |
| Before launch, or terminal | not 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 phase | Your status | Displayed |
|---|---|---|
| Accepted, not yet launched | not polled | Pending |
Live, before earliestProposalTs | any | Pending |
Live, before timeoutTs | Pending or invalid | Pending |
| Live | Resolving | Resolving |
Live, after timeoutTs | invalid | Unknown |
| Proposal standing | Pending or Resolving | Resolving |
| Proposal standing | Dispute (disputable resolvers only) | Dispute |
| Cancelled / Failed before launch | not polled | Cancelled / Failed |
| Resolved / Voided | any | Resolved / Voided |
Your message is always shown. Reporting Resolved before the chain says so is ignored.