<!-- canonical: https://docs.melee.markets/resolver-api/api/resolvers | markdown: https://docs.melee.markets/resolver-api/api/resolvers.md | index: https://docs.melee.markets/llms.txt -->
# Resolver management

| Method & path | Purpose |
|---|---|
| `POST /resolvers` | Register. Unauthenticated; returns credentials once. |
| `POST /resolvers/credentials/claim` | After Melee revoked and reissued your credentials: claim new ones. Unauthenticated; proves ownership of your registered authority keys and returns credentials once. See [Credential revocation and reclaim](/resolver-api/registration#credential-revocation-and-reclaim). |
| `POST /resolvers/me/activate` | Body `{ payer? }`. Smoke check + registration transaction; once that has confirmed, returns your record instead. See [Registration flow](/resolver-api/registration#registration-flow). |
| `POST /resolvers/me/smoke-check` | Re-run the smoke check on demand; returns `{ checks: [...] }`. |
| `POST /resolvers/me/reinstate` | From `Unhealthy`: re-run the smoke check and return to `Active` on success (returns your record); `422 smoke_check_failed` with the `checks` otherwise. |
| `GET /resolvers/me` | Your record (secrets omitted), including the `credentials` status, the `rulesGuidelinesReview` and your last [health probe](/resolver-api/registration#health). |
| `PATCH /resolvers/me` | Update off-chain fields: `name`, `description`, `rulesGuidelines`, `category`, `disputeUrl`, `baseUrl`, `trigger`. Returns the updated record. Changing `resolverAuthority` or `proposerAuthority` is coming soon (see below). |
| `DELETE /resolvers/me` | Retire. No new markets; existing markets remain yours. Returns the record; retiring an already retired resolver returns `200` with the record, so a retry is safe. |
| `GET /resolvers/me/confidence-threshold` | `{ minConfidenceBps }` |
| `PUT /resolvers/me/confidence-threshold` | Body `{ minConfidenceBps }` in `1..10000`. |
| `POST /resolvers/me/secrets/rotate` | Body `{ "secret": "apiSecret" }` or `{ "secret": "callbackSecret" }`. Returns the new value (and `keyId` for callback secrets) once. The old value stays valid for 1 hour; rotating the same secret again within that hour is `409 rotation_in_progress`. Not available while your credentials are revoked. |

**Updating your record.** Send only the fields you want to change, or send back the record from
`GET /resolvers/me` with your changes: a field sent with its current value is ignored, and `health`,
`credentials` and `rulesGuidelinesReview` are ignored whatever they hold, because Melee changes them on its own.
These are refused as `422 invalid_config`, with one `errors` entry per field, and nothing is changed:

| `reason` | Fields |
|---|---|
| `read_only` | A different `resolverId`, `state`, `verified` or `network`: set by Melee. |
| `not_patchable` | A different `minConfidenceBps` (use `PUT /resolvers/me/confidence-threshold`), `resolutionFeeRateBps`, `upFrontFees` or `feeRecipient` (set at registration; `PATCH` can't change them), or `disputable` (fixed at registration). Also a different `resolverAuthority` or `proposerAuthority`: changing your keys needs an on-chain transaction, which this API will issue soon; until then only the current value is accepted. `message` says why the field was refused. |
| `unknown_field` | Any other key, usually a typo. |

## Platform reference data (authenticated)

| Method & path | Purpose |
|---|---|
| `GET /platform/programs` | `{ network, programs: [{ programId, status: "Active" \| "Deprecated", since }] }` — the Melee program ids currently in use on this network. Markets name their `programId` in every payload; validate it against this list. See [Environments & testing](/resolver-api/environments#program-ids). |
| `GET /platform/creation-fee-mints` | `{ mints: [{ mint, tokenProgram, isDefault }] }` — the mints Melee can charge creation fees in, read from the on-chain platform config (the default first). Answers `503 temporarily_unavailable` with `Retry-After` while that config cannot be read; never an empty list. See [Fees](/resolver-api/fees). |
| `GET /platform/limits` | `{ resolutionFeeRateBps: { min, max }, platformMinConfidenceBps, handshakeTimeoutSecs: { default, max }, triggerOffsetSecs: { min, max }, text: { title, description, rules, rulesGuidelines, label, notes, rationale, message, resolverName, resolverDescription } }` — current bounds. `description` is the market description; `resolverName` and `resolverDescription` are your own record's `name` and `description`. `resolutionFeeRateBps` is the range markets can carry now: `0`–`0` while the program new markets use has no resolution fees ([Contract versions](/resolver-api/reference#contract-versions)); registration still accepts your rate within the configured range. |
| `GET /platform/callback-sources` | `{ cidrs: [...] }` — source addresses Melee calls you from, for allowlisting. |

## `POST /resolvers` — request

```json
{
  "name": "Example Sports Data",
  "description": "Official league feeds for major North American leagues.",
  "rulesGuidelines": "Identify the competition, teams, and scheduled event. Use the league's official result. State whether overtime counts and how postponed, abandoned, or cancelled events are handled.",
  "category": "DataFeed",
  "resolverAuthority": "<pubkey>",
  "feeRecipient": "<pubkey>",
  "resolutionFeeRateBps": 50,
  "upFrontFees": [ { "mint": "Es9v…", "amount": 10000000 }, { "mint": "EPjF…", "amount": 10000000 } ],
  "minConfidenceBps": 8000,
  "disputable": false,
  "baseUrl": "https://resolver.example.com/melee",
  "trigger": { "type": "EndTime", "offsetSecs": 900 },
  "issuedAt": 1790164800,
  "authorityProofs": { "resolverAuthority": "<base58 Ed25519 signature>" }
}
```

`authorityProofs` proves you control the keys you register; see
[Proof of key ownership](/resolver-api/registration#proof-of-key-ownership).

`rulesGuidelines` is optional and defaults to `""`. It is limited to 4000 characters, cannot contain links,
and takes effect as soon as it passes those checks; Melee may reject it later at its discretion. A refusal is
`422 invalid_config` with `errors: [{ field: "rulesGuidelines", reason, message }]`, where `reason` is one of
`too_long`, `contains_link`, `not_approved` (the text matches guidelines Melee already rejected); on registration nothing is created, so fix the field and
register again. A `201` means the guidelines were accepted and stored, and `GET /resolvers/me` returns them as
saved until Melee rejects them; it then returns the previous guidelines, or none, with the rejection in
`rulesGuidelinesReview`. See [Rules guidelines](/resolver-api/registration#how-you-know-your-guidelines-were-accepted).

## `POST /resolvers` — response (credentials are shown once)

```json
{
  "resolverId": "5f2c9a1e-…",
  "state": "PendingActivation",
  "network": "devnet",
  "apiKey": "mk_test_…",
  "apiSecret": "…",
  "callbackSecret": "…",
  "callbackKeyId": "ck_01"
}
```

API keys are prefixed `mk_test_` on devnet and `mk_live_` on mainnet.

## `POST /resolvers/credentials/claim`

Only after Melee has revoked your credentials and reissued them. No HMAC headers and no `Idempotency-Key`;
`authorityProofs` are signatures by your **registered** keys over the claim (see
[Credential claim proof](/resolver-api/reference#credential-claim-proof)).

```json
{
  "apiKey": "mk_test_…",
  "issuedAt": 1790164800,
  "authorityProofs": { "resolverAuthority": "<base58 Ed25519 signature>" }
}
```

`200` returns the same shape as the registration response, with a fresh `apiSecret`, `callbackSecret` and the
next `callbackKeyId`, shown once; `apiKey` and `resolverId` are unchanged. The new secrets take effect with
your first request signed with the new `apiSecret`. Errors: `422 invalid_config`, `409 claim_not_pending`,
`410 claim_expired`, `503 temporarily_unavailable`. See
[Credential revocation and reclaim](/resolver-api/registration#credential-revocation-and-reclaim).

## `POST /resolvers/me/activate` — response

Returns a [transaction envelope](/resolver-api/api/actions#transaction-envelope). Sign it with
`resolverAuthority` (and `proposerAuthority` if distinct) plus your payer, then submit via
`POST /transactions/{transactionId}`. If the smoke check fails you receive `422 smoke_check_failed`:

```json
{
  "code": "smoke_check_failed",
  "checks": [
    { "name": "health", "ok": true, "status": 200, "latencyMs": 84 },
    { "name": "status_probe", "ok": false, "status": 200, "expected": "404 {\"code\":\"unknown_market\"}", "detail": "returned a status object for the probe market" },
    { "name": "evaluate_probe", "ok": false, "detail": "unreachable: connection refused" }
  ]
}
```

When we could not get a response at all, `detail` is `unreachable: <reason>` with one of these reasons:
`the host name does not resolve`, `the host does not resolve to a public address`, `TLS handshake failed`,
`connection refused`, `could not connect (timed out)`, `could not connect`, `the response was not valid HTTP`
(also when the response breaks off mid-body), or `no response within N s`. We don't include addresses or
lower-level error text.
