<!-- canonical: https://docs.melee.markets/resolver-api/your-endpoints | markdown: https://docs.melee.markets/resolver-api/your-endpoints.md | index: https://docs.melee.markets/llms.txt -->
# Endpoints you implement

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

```http
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](/resolver-api/reference#hmac-signing).
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](/resolver-api/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](/resolver-api/changes) 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](/resolver-api/lifecycle) | `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`](/resolver-api/api/markets), where
`triggerType` is `null` and `sentAt` is the response time.

```json
{
  "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](/resolver-api/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](/resolver-api/reference#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}`

```json
{ "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.

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

`200` with `ok: true` within 10 seconds means healthy. Anything else counts toward
[`Unhealthy`](/resolver-api/registration#unhealthy-suspension-and-reinstatement). 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.
