Skip to Content
Draft v0.2 — this specification is under active design and may change before implementation.
Resolver APIMelee Resolver APIAuthentication & conventions

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, PUT and PATCH accepts Idempotency-Key (UUID); registration (POST /resolvers) requires it. Replays within 24 h return the original response; a different body under the same key returns 409 idempotency_conflict. For registration only successful responses are kept, so after a 4xx you 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 code field is stable and is what your integration should branch on; detail is for people. Some codes add members, such as currentVersion and currentHash here, and a 500 internal_error carries a traceId. See Failure modes for the full list.

  • Rate limits return 429 rate_limited with Retry-After. Defaults, per resolver:

    SurfaceLimit
    GET /markets/{market}/status1 per minute per market
    GET /markets6 per minute
    Resolution actions30 per minute
    Everything else60 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) and POST /resolvers/credentials/claim share 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). outcomeIndex is the unambiguous choice.

  • Definition hash. Resolution actions carry the definitionHash of the market version you are acting on. See Verifying the definition.

Last updated on