Melee Resolver API
Base URL and versioning
https://api.melee.markets/api/resolver/v1/ (devnet: https://api.dev.melee.markets/api/resolver/v1/).
The path carries the major version. Additive changes (new optional fields, new endpoints) do not bump it.
Authentication
Every request except POST /resolvers and POST /resolvers/credentials/claim carries:
X-Melee-Api-Key: <apiKey>
X-Melee-Timestamp: <unix millis>
X-Melee-Signature: <hex lowercase HMAC-SHA256>Signature input, with body empty for GET:
toSign = "{METHOD} {path-with-query} {sha256hex(body)} {apiKey} {timestampMillis}"
signature = HMAC-SHA256(apiSecret, toSign)Requests with a timestamp more than 5 minutes from server time are rejected (401 auth_failed).
Example (Node.js)
import { createHash, createHmac } from 'node:crypto'
function sign({ method, pathWithQuery, body = '', apiKey, apiSecret }) {
const ts = Date.now().toString()
const bodyHash = createHash('sha256').update(body).digest('hex')
const toSign = `${method} ${pathWithQuery} ${bodyHash} ${apiKey} ${ts}`
const signature = createHmac('sha256', apiSecret).update(toSign).digest('hex')
return {
'X-Melee-Api-Key': apiKey,
'X-Melee-Timestamp': ts,
'X-Melee-Signature': signature,
}
}Conventions
-
JSON, camelCase. Timestamps are Unix seconds unless the field ends in
Millis. Pubkeys are base58. Basis points are out of 10,000. -
Idempotency. Every
POST,PUTandPATCHacceptsIdempotency-Key(UUID); registration (POST /resolvers) requires it. Replays within 24 h return the original response; a different body under the same key returns409 idempotency_conflict. For registration only successful responses are kept, so after a4xxyou can retry with the same key. -
Errors use
application/problem+json:{ "type": "https://docs.melee.markets/resolver-api/errors#definition_mismatch", "title": "Definition mismatch", "status": 409, "code": "definition_mismatch", "detail": "definitionHash is not the market's current definition. Fetch GET /markets/{market}/definition, review it and retry.", "currentVersion": 3, "currentHash": "9f2a…" }The
codefield is stable and is what your integration should branch on;detailis for people. Some codes add members, such ascurrentVersionandcurrentHashhere, and a500 internal_errorcarries atraceId. See Failure modes for the full list. -
Rate limits return
429 rate_limitedwithRetry-After. Defaults, per resolver:Surface Limit GET /markets/{market}/status1 per minute per market GET /markets6 per minute Resolution actions 30 per minute Everything else 60 per minute Each request counts toward exactly one of these. Independently of your resolver, every client IP may send 50 requests per second (bursts up to 100), and
POST /resolvers(registration) andPOST /resolvers/credentials/claimshare a limit of 10 per hour per IP. -
Outcome references. Wherever an outcome is required you may pass one of
{ "outcomeIndex": 1 },{ "outcomePubkey": "…" }, or{ "outcomeLabel": "Yes" }. Labels match the outcome title exactly after trimming, case-insensitively; zero or multiple matches are rejected (outcome_not_found,outcome_ambiguous).outcomeIndexis the unambiguous choice. -
Definition hash. Resolution actions carry the
definitionHashof the market version you are acting on. See Verifying the definition.