<!-- canonical: https://docs.melee.markets/resolver-api/api | markdown: https://docs.melee.markets/resolver-api/api.md | index: https://docs.melee.markets/llms.txt -->
# 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:

```http
X-Melee-Api-Key:    <apiKey>
X-Melee-Timestamp:  <unix millis>
X-Melee-Signature:  <hex lowercase HMAC-SHA256>
```

Signature input, with `body` empty for GET:

```text
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)

```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`:

  ```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](/resolver-api/errors) for the full list.
- **Rate limits** return `429 rate_limited` with `Retry-After`. Defaults, per resolver:

  | Surface | Limit |
  |---|---|
  | `GET /markets/{market}/status` | 1 per minute per market |
  | `GET /markets` | 6 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) 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](/resolver-api/definition).
