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

Registration

Registration is per environment. Register on devnet first (see Environments & testing); devnet and mainnet credentials, resolver ids and on-chain accounts are independent.

The resolver record

FieldTypeRequiredNotes
resolverIdUUIDassignedIssued by Melee at registration.
namestring ≤ 64yesDisplayed to market creators and traders. Must not be used by another resolver that isn’t retired, compared case- and whitespace-insensitively.
descriptionstring ≤ 512noDisplayed.
rulesGuidelinesstring ≤ 4000noPublic plain-text guidance for creators drafting and revising rules. No links. Defaults to "". See Rules guidelines.
categoryenum ResolverCategoryyesDisplay-only classification.
resolverAuthoritypubkeyyesSigns resolve, reject and void transactions and signs acceptance evidence. Must be a fresh Ed25519 key that has never been used on Melee (Melee creates its user account at activation).
proposerAuthoritypubkeynoOnly when disputable = true. Defaults to resolverAuthority. Same freshness rule.
feeRecipientpubkeynoWallet that receives your fees. Defaults to resolverAuthority. Any wallet.
resolutionFeeRateBpsu16noTrading-based fee, basis points. Defaults to the platform default. Range published by GET /platform/limits. Not charged on the current program; see Contract versions.
upFrontFeesarray of { mint, amount }, at most 4noFixed fee charged to the market creator when a market is created with you as resolver, per creation-fee mint. amount is a JSON integer in base units (≤ 2^53−1). See Fees. Never refunded. Stored, but not charged yet (Contract versions).
minConfidenceBpsu16yesYour own floor, 1..10000. See the confidence policy.
disputableboolyesWhether you run a dispute process between propose and resolve.
disputeUrlURL templateif disputableWhere users view or file disputes. May contain {marketPubkey}.
baseUrlHTTPS URLyesRoot of the endpoints you implement. May include a path prefix. Must use port 443.
triggerobject TriggerSubscriptionyesHow you want to be notified when a market’s event has concluded.
authorityProofsobjectyesProof that you control the keys you register: { resolverAuthority, proposerAuthority? }, each a detached Ed25519 signature (base58) by that key. See Proof of key ownership.
issuedAtinteger, Unix secondsyesWhen you built the request; must be within 5 minutes of Melee’s clock. Covered by the proof, so a captured proof expires. Not stored.
verifiedboolplatform-setMelee marks resolvers it has vetted. Displayed as a badge.
stateenum ResolverStateplatform-setPendingActivation, Active, Unhealthy, Suspended, Retired.
credentialsobjectplatform-set{ status, revokedAt?, claimExpiresAt?, reissuedAt? }: whether Melee has revoked your secrets. Independent of state. Ignored if sent in a PATCH. See Credential revocation and reclaim.
rulesGuidelinesReviewobjectplatform-set{ status, revision, pendingRulesGuidelines?, rejectionReason?, reviewedAt?, submittedAt? }: Melee’s review of your rulesGuidelines. Ignored if sent in a PATCH. See How you know your guidelines were accepted.
healthobjectplatform-set{ lastProbeAt, lastResult, consecutiveFailures, failingSince, unhealthySince }: the last health probe. Absent until the first probe. Ignored if sent in a PATCH. See Health.

Rules guidelines

rulesGuidelines helps creators draft rules you are more likely to accept, reducing back-and-forth before acceptance. Describe common rejection reasons, preferred sources by name, required details, and examples of acceptable rules. Creators can read your guidelines when choosing a resolver and use them when drafting or revising their market’s rules.

  • Maximum 4,000 characters, including spaces and line breaks. Oversized values are rejected, never truncated.
  • No links. A value is rejected if it contains a URL scheme (http://, https://, ftp://, mailto:), a www. prefix, a Markdown link ([text](target)), an HTML anchor, or a bare domain such as espn.com. You may name a source in words, such as “the NBA’s official results” or “ESPN”, without linking to it.
  • Live at once; Melee may reject later. Guidelines that pass the length and link checks take effect immediately. Melee may reject them afterwards at its discretion; see How you know your guidelines were accepted.
  • Set guidelines during registration or update them through PATCH /resolvers/me. Omit the field in a patch to leave it unchanged; set it to "" to clear it. Updates apply to subsequent drafting and revision only; they do not rewrite existing drafts or rules, or invalidate acceptance.

How you know your guidelines were accepted

Validation is all-or-nothing. A 201 from POST /resolvers means every field, including rulesGuidelines, passed and is stored; GET /resolvers/me returns the guidelines exactly as saved unless Melee later rejects them (see below). A 200 from PATCH /resolvers/me means the same for an update.

When guidelines are refused, registration fails as a whole: no resolverId is issued and no credentials are created, so you simply fix the field and register again. A refused patch leaves your record unchanged. The 422 invalid_config body names the field and a stable reason you can branch on:

{ "type": "https://docs.melee.markets/resolver-api/errors#invalid_config", "title": "Registration failed validation", "status": 422, "code": "invalid_config", "detail": "rulesGuidelines was rejected. Nothing was registered; fix the field and submit again.", "errors": [ { "field": "rulesGuidelines", "reason": "contains_link", "message": "Links are not allowed in rules guidelines. Remove \"https://stats.example.com/results\" and name the source in words instead." } ] }
reasonMeaning
too_longMore than 4000 characters. message states the length received
contains_linkA link was found. message quotes the offending text
not_approvedThe text exactly matches guidelines Melee already rejected for your resolver

The same errors entry, with field: "rulesGuidelines", is returned by PATCH /resolvers/me. Other invalid fields in the same request are listed alongside it, one entry per field.

Accepted guidelines take effect immediately, but Melee may still reject them later. When that happens, your previous accepted guidelines come back into effect, or none if there were none. GET /resolvers/me then returns the guidelines in effect as rulesGuidelines, and rulesGuidelinesReview shows status: "Rejected" with the rejected text in pendingRulesGuidelines and Melee’s reason in rejectionReason. Submitting the exact rejected text again is refused with not_approved; edit it and submit again.

New submissions go live once they pass the checks above. status: "Pending", with the text in pendingRulesGuidelines, only appears for a submission held for Melee’s review, which does not happen today except for revisions submitted before guidelines went live by default.

Guidelines are drafting assistance only. Your evaluation and acceptance still determine whether the exact market rules are sufficient. Guidelines are not part of the market definition or its hash, and following them does not guarantee acceptance. Any terms that determine a market’s outcome must appear in its accepted rules.

Enums

ResolverCategory = DataFeed | Oracle | Authority DataFeed – an authoritative data provider Oracle – a data aggregator Authority – a single authoritative party, typically a person or organization TriggerType = EndTime | Creator | None ResolverState = PendingActivation | Active | Unhealthy | Suspended | Retired ResolutionStatus (what your status endpoint returns) = Pending | Resolving | Dispute | Resolved DisplayStatus (what Melee shows; derived from chain state, lifecycle events and your status) = Pending | Resolving | Dispute | Resolved | Voided | Cancelled | Failed | Unknown

Trigger subscription

{ "type": "EndTime", "offsetSecs": 0 }
typeMeaningoffsetSecs
EndTimeWe call POST {baseUrl}/trigger at endDate + offsetSecs for each of your markets.required; signed integer between −604800 (7 days early) and +43200 (12 hours late)
CreatorThe market creator asks us to notify you; we forward the request to POST {baseUrl}/trigger. May repeat if the creator asks again.ignored
NoneYou monitor markets yourself via the poll endpoints.ignored

Proof of key ownership

Registration must prove that you control the key you register, so nobody can register someone else’s public key and block its real owner. You don’t need to build this by hand:

  1. Create your resolver key (a normal Solana keypair, never used on Melee): solana-keygen new -o resolver-authority.json.
  2. Run the ready-made script (TypeScript, Python or plain terminal) with your own fields. It signs the request and prints the complete JSON body, authorityProofs included.
  3. Send that output as-is to POST /resolvers with an Idempotency-Key header (a UUID you keep):
curl -X POST https://api.dev.melee.markets/api/resolver/v1/resolvers \ -H "Content-Type: application/json" \ -H "Idempotency-Key: $(uuidgen)" \ -d @registration.json

Send it within 5 minutes: the script stamps the body with the current time (issuedAt), and Melee refuses an older one with proof_expired. Just run the script again. If you set a separate proposerAuthority, the script signs with that key too.

How the proof works

The script signs, with resolverAuthority (and with proposerAuthority when it is a different key), the message

message = "melee-register:v1:" + network + ":" + sha256hex( JCS( request body without authorityProofs ) )

JCS is the canonical JSON used for the definition hash, and the signature is a plain detached Ed25519 signature in base58, sent in authorityProofs. Because it covers the whole body, a captured proof can’t be reused with a different baseUrl or different fees. network (devnet, as GET /platform/programs reports it) means a proof is refused on any other network, and issuedAt (within 5 minutes of our clock) means a captured proof expires. A test vector is in the Integration reference.

A missing or non-verifying proof is 422 invalid_config with errors[].field = "authorityProofs.resolverAuthority" (or .proposerAuthority) and reason proof_missing or proof_invalid; for proof_invalid the message quotes the exact string that must be signed. An issuedAt outside the 5-minute window is 422 invalid_config with errors[].field = "issuedAt" and reason proof_expired: run the script again and resend.

Validation rules

Registration is rejected (invalid_config) unless all of these hold:

  • disputable = true ⇒ disputeUrl present.
  • proposerAuthority present ⇒ disputable = true.
  • trigger.type = EndTime ⇒ offsetSecs present and within range.
  • baseUrl is HTTPS on the default port (443); no other port is accepted.
  • resolutionFeeRateBps within the platform range; minConfidenceBps in 1..10000.
  • upFrontFees has at most 4 entries with distinct mints.
  • rulesGuidelines, when supplied, is at most 4000 characters, contains no links, and is not text Melee already rejected. A failure is reported with errors[].field = "rulesGuidelines" and a reason of too_long, contains_link or not_approved (see Rules guidelines). The same checks apply when updating guidelines.
  • resolverAuthority and proposerAuthority are valid Solana public keys, are not registered to another resolver, and have no existing Melee user account.
  • authorityProofs verifies for resolverAuthority, and for proposerAuthority when it differs.
  • name is not already used by another resolver (ignoring case and extra spaces); a clash is reported with reason: name_taken.

Registration flow

Registration is two API calls plus one transaction.

  1. Register. Returns your credentials once: apiKey, apiSecret, callbackSecret and its keyId. Store them securely; they are not retrievable later (rotate instead, see Resolver management). Registration requires an Idempotency-Key header (a UUID you generate and keep); without it you get 422 invalid_config with errors[].field = "Idempotency-Key" and reason required. If the response is lost, retrying with the same key and body within 24 hours returns the same credentials. Treat that key like a password until you have stored the credentials. A rejected registration (any 4xx, for example invalid_config or proof_expired) is not kept, so you can fix the request and retry with the same key.
  2. Activate. We run the smoke check:
    • GET {baseUrl}/health must return 200 with { "ok": true }.
    • GET {baseUrl}/status/{probeMarket} must return HTTP 404 with the JSON body { "code": "unknown_market" } (the probe market pubkey does not exist; it is MeLeeProbe11111111111111111111111111111111). The body proves the route is yours rather than a framework’s catch-all 404.
    • POST {baseUrl}/evaluate is sent with "probe": true in the envelope and a proposalId starting with probe-; it must return 200 with confidenceBps: 0. If all pass, we return the registration transaction. It creates the on-chain Melee user accounts of your resolverAuthority and of a distinct proposerAuthority (and, on a program with resolution fees, of a distinct feeRecipient that has none yet). Melee’s own signature is already in the transaction; you add resolverAuthority (and proposerAuthority if distinct) and the payer. The payer defaults to resolverAuthority; name another key you control with { "payer": "…" } in the activate body. Calling activate again while that transaction is outstanding returns the same envelope, and once it has confirmed, activate returns your record (now Active) with nothing left to sign. The smoke check runs at most once every 10 seconds; sooner is 429 rate_limited with Retry-After. See Integration reference.
  3. Submit. Post the signed transaction back to us. On confirmation your state becomes Active and market creators can select you.

Activation registers you on the program that new markets use. When Melee deploys a new version of its markets program, it registers every activated resolver there itself, at its own cost; you sign and pay nothing. Until that has run for you, creators can’t select you for markets on the new program. See Contract versions.

Your verified badge is granted separately by Melee after review. Creators may select unverified resolvers; the UI tells them which is which.

Why PendingActivation exists

The smoke check cannot run until your endpoints know the callbackSecret, and your on-chain accounts cannot exist until you have signed. While PendingActivation you can read and update your record, rotate secrets, and retry activate as often as needed. You cannot be selected for markets or call resolution endpoints. Registrations never activated expire after 30 days.

Unhealthy, suspension and reinstatement

While you are Active, we probe GET {baseUrl}/health every few minutes (unsigned; healthy means 200 with { "ok": true } within 10 seconds). After 5 consecutive failures, the first at least 15 minutes ago, your state becomes Unhealthy: creators can no longer select you, but existing markets are unaffected and you can still resolve them. Probing stops while you are Unhealthy. Reinstate yourself with POST /resolvers/me/reinstate, which re-runs the smoke check and returns you to Active when every probe passes; otherwise it answers 422 smoke_check_failed with the checks, and you stay Unhealthy.

Health

health on your record shows the last probe. It is absent until the first one. Times are Unix seconds.

FieldMeaning
lastProbeAtWhen the last probe, or the smoke check of a successful reinstatement, ran
lastResultok or failed
consecutiveFailuresFailed probes in a row; a healthy probe resets it to 0
failingSinceThe first failure of the current run; null while healthy
unhealthySinceWhen the failures made you Unhealthy; null unless you are Unhealthy

Outside Active the values are those of the last probe.

Suspension

Suspended is different: Melee sets it when it finds a resolver acting in bad faith. A suspended resolver can only read. Every other call is 403 resolver_suspended, including market actions on markets you already resolve, and there is no self-serve way back. When it suspends you, Melee may also plan to void your open markets (platformVoidReason: "Operator"). The program lets Melee void a market only from its timeoutTs, so a planned void is sent once timeoutTs plus a 24-hour grace has passed (see Platform void). If Melee lifts the suspension, you return to the state you had before, and planned voids that have not been sent yet are normally withdrawn.

What each state may do

StateReadsUpdate your record, smoke check, confidence thresholdRotate secretsMarket actionsactivatereinstateRetire (DELETE /resolvers/me)
PendingActivationyesyesyesno (no markets yet)yesnoyes
Activeyesyesyesyesnonoyes
Unhealthyyesyesyesyesnoyesyes
Suspendedyesnononononono
Retiredyesnoyesyes, for markets you already acceptednonoyes (returns your record)

Reads are every GET. Market actions are propose, resolve, void, reject, rules updates and answers to rules requests, claim-fees and fee-recipient. POST /transactions/{transactionId} is open in every state except Suspended (PendingActivation submits its activation transaction there). A call your state does not allow is 403 resolver_state_forbidden, with detail naming the states that may call it, or 403 resolver_suspended while you are suspended.

Credential revocation and reclaim

If your apiSecret or callbackSecret leaks, rotating it leaves the old value valid for another hour. When that is too long, ask Melee to revoke your credentials. Melee may also revoke them on its own when it learns of a leak. Revocation cuts off both secrets at once, and you get new ones by claiming them yourself with your resolver keys. Melee never sees the new secrets.

Revocation is not a state

UnhealthySuspendedRevocation
AboutFailed health probesBad faith, decided by MeleeYour secrets
stateBecomes UnhealthyBecomes SuspendedUnchanged
Your API requestsKeep working, your existing markets includedReads only; the rest is 403 resolver_suspendedEvery request is refused with 401 credentials_revoked
Callbacks to youUnchangedUnchangedHeld, then delivered after you confirm new credentials
Existing marketsUnaffectedMelee may plan to void themUnaffected; nothing is changed on them
New marketsYou can’t be selectedYou can’t be selectedYou can’t be selected
Way backPOST /resolvers/me/reinstate yourselfOnly Melee can lift itMelee reissues, you claim and confirm new secrets

Revocation is independent of your state: a resolver can be Unhealthy or Suspended and revoked at the same time.

While your credentials are revoked

  • Every request signed with your current or previous apiSecret, including one still in its rotation overlap, answers 401 credentials_revoked. There is no overlap. A request that does not verify at all still answers 401 auth_failed, so credentials_revoked always means the secret is right and Melee has revoked it.
  • You can’t rotate. POST /resolvers/me/secrets/rotate is refused like every other request. New secrets come only from a claim.
  • Callbacks are held. Melee sends nothing signed with your revoked callbackSecret. Pending notifications (/live, /applied, /cancelled, /lifecycle, /trigger, rules requests) stay queued, and the time they spend held does not count against their 24-hour retry window. Melee doesn’t call your status endpoint either. Melee’s unsigned GET {baseUrl}/health probe keeps running.
  • Your markets stay as they are. Your state, your markets and your bindings to them don’t change. You can’t be selected for new markets, because the acceptance handshake can’t be signed.
  • Nothing is voided for time. Melee never voids a market because it is late, revoked or not (platform voids). Your markets wait for you to claim new credentials and resolve them.
  • You can’t see your status. GET /resolvers/me is refused too, so you never see revoked or claimable on it. Don’t poll it to learn when a claim opens: Melee tells you directly.

Reclaim: reissue, claim, confirm

  1. Melee reissues. Once the cause of the leak is fixed, Melee reissues your credentials. A reissue only opens a claim window, 24 hours by default. It creates no secret and shows Melee none. Melee tells you when the window is open and when it closes.

  2. Claim. Call POST /resolvers/credentials/claim within the window. The request carries no HMAC headers, since no request signed with a revoked secret is accepted. Instead you prove you control the authority keys you registered, the same way as at registration, with the message prefix melee-claim-credentials:v1: (byte-exact rules and a test vector in the Integration reference):

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

    The proofs must be by your registered resolverAuthority, and by proposerAuthority when that is a different key. issuedAt must be within 5 minutes of Melee’s clock. The response returns a fresh apiSecret and callbackSecret (with the next callbackKeyId) once, in the same shape as the registration response. Your apiKey and resolverId don’t change.

  3. Confirm. Nothing takes effect on the claim. Your old secrets still answer credentials_revoked, and callbacks stay held. Your first request signed with the new apiSecret confirms the claim. Melee makes the new secrets current before it serves that request, drops every older secret with no overlap, and resumes the held callbacks, which are now signed with the new callbackSecret and X-Melee-Key-Id. So install the new callbackSecret on your endpoints before you send that request. Any signed request works; GET /resolvers/me is a natural one, and its credentials then shows active with reissuedAt.

If the claim response is lost, claim again inside the window with a later issuedAt (sign a fresh request). The new secrets replace the unconfirmed ones; the lost set never works and is answered with auth_failed. A claim request is never accepted twice: an issuedAt no later than the last claim’s is refused, so a captured claim can’t be replayed. Secrets you claimed but haven’t confirmed stay confirmable after the window closes, until Melee reissues again.

If the window closes before you claim, the claim answers 410 claim_expired; ask Melee to reissue. Melee can also cancel an open window, for example if it suspects your authority keys are compromised too. That discards any unconfirmed claimed secrets, and a claim then answers 409 claim_not_pending.

Claim responseMeaning
200New credentials, shown once. Confirm them with your first signed request.
422 invalid_configA field or proof was rejected, nothing was issued. errors[].field is apiKey (missing or not a registered key), issuedAt (proof_expired: outside 5 minutes, or not later than the last claim’s) or authorityProofs.resolverAuthority / .proposerAuthority (proof_missing, proof_invalid; message quotes the exact string to sign).
409 claim_not_pendingNo claim is open: your credentials are not revoked, Melee hasn’t reissued yet, the window was cancelled, or claimed credentials were already confirmed.
410 claim_expiredThe window closed. Ask Melee to reissue.
503 temporarily_unavailableNothing was changed. Sign a fresh request and retry after Retry-After.

Your proofs are checked before the claim’s state, so without your keys nobody can learn whether a claim is open. The endpoint shares registration’s rate limit.

The credentials member

GET /resolvers/me returns credentials next to state. Times are Unix seconds.

FieldMeaning
statusactive, revoked (every request refused) or claimable (still revoked, and a claim window is open)
revokedAtWhen Melee revoked your credentials. Only while revoked or claimable
claimExpiresAtWhen the open claim window closes. Only while claimable
reissuedAtWhen you last confirmed reissued credentials. Absent if that never happened

Since every signed request is refused while revoked, in practice you only ever read active, with reissuedAt after a reissue. revoked and claimable are part of the record’s shape, not something to wait for.

Retiring

DELETE /resolvers/me moves you to Retired and returns your record: no new markets can select you; markets you already accepted remain yours to resolve, and market actions and transactions keep working for them. You can still read and rotate secrets, but no longer change your record. Retiring again returns your record unchanged, so a retry is safe. A suspended resolver can’t retire (403 resolver_suspended).

Last updated on