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
| Field | Type | Required | Notes |
|---|---|---|---|
resolverId | UUID | assigned | Issued by Melee at registration. |
name | string ≤ 64 | yes | Displayed to market creators and traders. Must not be used by another resolver that isn’t retired, compared case- and whitespace-insensitively. |
description | string ≤ 512 | no | Displayed. |
rulesGuidelines | string ≤ 4000 | no | Public plain-text guidance for creators drafting and revising rules. No links. Defaults to "". See Rules guidelines. |
category | enum ResolverCategory | yes | Display-only classification. |
resolverAuthority | pubkey | yes | Signs 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). |
proposerAuthority | pubkey | no | Only when disputable = true. Defaults to resolverAuthority. Same freshness rule. |
feeRecipient | pubkey | no | Wallet that receives your fees. Defaults to resolverAuthority. Any wallet. |
resolutionFeeRateBps | u16 | no | Trading-based fee, basis points. Defaults to the platform default. Range published by GET /platform/limits. Not charged on the current program; see Contract versions. |
upFrontFees | array of { mint, amount }, at most 4 | no | Fixed 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). |
minConfidenceBps | u16 | yes | Your own floor, 1..10000. See the confidence policy. |
disputable | bool | yes | Whether you run a dispute process between propose and resolve. |
disputeUrl | URL template | if disputable | Where users view or file disputes. May contain {marketPubkey}. |
baseUrl | HTTPS URL | yes | Root of the endpoints you implement. May include a path prefix. Must use port 443. |
trigger | object TriggerSubscription | yes | How you want to be notified when a market’s event has concluded. |
authorityProofs | object | yes | Proof that you control the keys you register: { resolverAuthority, proposerAuthority? }, each a detached Ed25519 signature (base58) by that key. See Proof of key ownership. |
issuedAt | integer, Unix seconds | yes | When you built the request; must be within 5 minutes of Melee’s clock. Covered by the proof, so a captured proof expires. Not stored. |
verified | bool | platform-set | Melee marks resolvers it has vetted. Displayed as a badge. |
state | enum ResolverState | platform-set | PendingActivation, Active, Unhealthy, Suspended, Retired. |
credentials | object | platform-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. |
rulesGuidelinesReview | object | platform-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. |
health | object | platform-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:), awww.prefix, a Markdown link ([text](target)), an HTML anchor, or a bare domain such asespn.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."
}
]
}reason | Meaning |
|---|---|
too_long | More than 4000 characters. message states the length received |
contains_link | A link was found. message quotes the offending text |
not_approved | The 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 | UnknownTrigger subscription
{ "type": "EndTime", "offsetSecs": 0 }type | Meaning | offsetSecs |
|---|---|---|
EndTime | We 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) |
Creator | The market creator asks us to notify you; we forward the request to POST {baseUrl}/trigger. May repeat if the creator asks again. | ignored |
None | You 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:
- Create your resolver key (a normal Solana keypair, never used on Melee):
solana-keygen new -o resolver-authority.json. - Run the ready-made script (TypeScript, Python or plain terminal)
with your own fields. It signs the request and prints the complete JSON body,
authorityProofsincluded. - Send that output as-is to
POST /resolverswith anIdempotency-Keyheader (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.jsonSend 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⇒disputeUrlpresent.proposerAuthoritypresent ⇒disputable = true.trigger.type = EndTime⇒offsetSecspresent and within range.baseUrlis HTTPS on the default port (443); no other port is accepted.resolutionFeeRateBpswithin the platform range;minConfidenceBpsin1..10000.upFrontFeeshas 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 witherrors[].field = "rulesGuidelines"and areasonoftoo_long,contains_linkornot_approved(see Rules guidelines). The same checks apply when updating guidelines.resolverAuthorityandproposerAuthorityare valid Solana public keys, are not registered to another resolver, and have no existing Melee user account.authorityProofsverifies forresolverAuthority, and forproposerAuthoritywhen it differs.nameis not already used by another resolver (ignoring case and extra spaces); a clash is reported withreason: name_taken.
Registration flow
Registration is two API calls plus one transaction.
- Register. Returns your credentials once:
apiKey,apiSecret,callbackSecretand itskeyId. Store them securely; they are not retrievable later (rotate instead, see Resolver management). Registration requires anIdempotency-Keyheader (a UUID you generate and keep); without it you get422 invalid_configwitherrors[].field = "Idempotency-Key"andreasonrequired. 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 (any4xx, for exampleinvalid_configorproof_expired) is not kept, so you can fix the request and retry with the same key. - Activate. We run the smoke check:
GET {baseUrl}/healthmust return200with{ "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 isMeLeeProbe11111111111111111111111111111111). The body proves the route is yours rather than a framework’s catch-all 404.POST {baseUrl}/evaluateis sent with"probe": truein the envelope and aproposalIdstarting withprobe-; it must return200withconfidenceBps: 0. If all pass, we return the registration transaction. It creates the on-chain Melee user accounts of yourresolverAuthorityand of a distinctproposerAuthority(and, on a program with resolution fees, of a distinctfeeRecipientthat has none yet). Melee’s own signature is already in the transaction; you addresolverAuthority(andproposerAuthorityif distinct) and the payer. The payer defaults toresolverAuthority; name another key you control with{ "payer": "…" }in theactivatebody. Callingactivateagain while that transaction is outstanding returns the same envelope, and once it has confirmed,activatereturns your record (nowActive) with nothing left to sign. The smoke check runs at most once every 10 seconds; sooner is429 rate_limitedwithRetry-After. See Integration reference.
- Submit. Post the signed transaction back to us. On confirmation your state becomes
Activeand 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.
| Field | Meaning |
|---|---|
lastProbeAt | When the last probe, or the smoke check of a successful reinstatement, ran |
lastResult | ok or failed |
consecutiveFailures | Failed probes in a row; a healthy probe resets it to 0 |
failingSince | The first failure of the current run; null while healthy |
unhealthySince | When 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
| State | Reads | Update your record, smoke check, confidence threshold | Rotate secrets | Market actions | activate | reinstate | Retire (DELETE /resolvers/me) |
|---|---|---|---|---|---|---|---|
PendingActivation | yes | yes | yes | no (no markets yet) | yes | no | yes |
Active | yes | yes | yes | yes | no | no | yes |
Unhealthy | yes | yes | yes | yes | no | yes | yes |
Suspended | yes | no | no | no | no | no | no |
Retired | yes | no | yes | yes, for markets you already accepted | no | no | yes (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
Unhealthy | Suspended | Revocation | |
|---|---|---|---|
| About | Failed health probes | Bad faith, decided by Melee | Your secrets |
state | Becomes Unhealthy | Becomes Suspended | Unchanged |
| Your API requests | Keep working, your existing markets included | Reads only; the rest is 403 resolver_suspended | Every request is refused with 401 credentials_revoked |
| Callbacks to you | Unchanged | Unchanged | Held, then delivered after you confirm new credentials |
| Existing markets | Unaffected | Melee may plan to void them | Unaffected; nothing is changed on them |
| New markets | You can’t be selected | You can’t be selected | You can’t be selected |
| Way back | POST /resolvers/me/reinstate yourself | Only Melee can lift it | Melee 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, answers401 credentials_revoked. There is no overlap. A request that does not verify at all still answers401 auth_failed, socredentials_revokedalways means the secret is right and Melee has revoked it. - You can’t rotate.
POST /resolvers/me/secrets/rotateis 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 unsignedGET {baseUrl}/healthprobe 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/meis refused too, so you never seerevokedorclaimableon it. Don’t poll it to learn when a claim opens: Melee tells you directly.
Reclaim: reissue, claim, confirm
-
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.
-
Claim. Call
POST /resolvers/credentials/claimwithin 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 prefixmelee-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 byproposerAuthoritywhen that is a different key.issuedAtmust be within 5 minutes of Melee’s clock. The response returns a freshapiSecretandcallbackSecret(with the nextcallbackKeyId) once, in the same shape as the registration response. YourapiKeyandresolverIddon’t change. -
Confirm. Nothing takes effect on the claim. Your old secrets still answer
credentials_revoked, and callbacks stay held. Your first request signed with the newapiSecretconfirms 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 newcallbackSecretandX-Melee-Key-Id. So install the newcallbackSecreton your endpoints before you send that request. Any signed request works;GET /resolvers/meis a natural one, and itscredentialsthen showsactivewithreissuedAt.
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 response | Meaning |
|---|---|
200 | New credentials, shown once. Confirm them with your first signed request. |
422 invalid_config | A 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_pending | No 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_expired | The window closed. Ask Melee to reissue. |
503 temporarily_unavailable | Nothing 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.
| Field | Meaning |
|---|---|
status | active, revoked (every request refused) or claimable (still revoked, and a claim window is open) |
revokedAt | When Melee revoked your credentials. Only while revoked or claimable |
claimExpiresAt | When the open claim window closes. Only while claimable |
reissuedAt | When 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).