Skip to Content
Draft v0.2 — this specification is under active design and may change before implementation.

Resolver management

Method & pathPurpose
POST /resolversRegister. Unauthenticated; returns credentials once.
POST /resolvers/credentials/claimAfter 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.
POST /resolvers/me/activateBody { payer? }. Smoke check + registration transaction; once that has confirmed, returns your record instead. See Registration flow.
POST /resolvers/me/smoke-checkRe-run the smoke check on demand; returns { checks: [...] }.
POST /resolvers/me/reinstateFrom 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/meYour record (secrets omitted), including the credentials status, the rulesGuidelinesReview and your last health probe.
PATCH /resolvers/meUpdate 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/meRetire. 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-thresholdBody { minConfidenceBps } in 1..10000.
POST /resolvers/me/secrets/rotateBody { "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:

reasonFields
read_onlyA different resolverId, state, verified or network: set by Melee.
not_patchableA 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_fieldAny other key, usually a typo.

Platform reference data (authenticated)

Method & pathPurpose
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.
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.
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); 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

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

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.

POST /resolvers — response (credentials are shown once)

{ "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).

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

POST /resolvers/me/activate — response

Returns a 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:

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

Last updated on