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

Integration reference

Everything on this page is normative. Where a test vector is given, your implementation must reproduce it.

HMAC signing

Both directions use the same construction. Only the roles differ.

Melee → you (callbacks)You → Melee (API)
SecretcallbackSecretapiSecret
Identity headerX-Melee-Resolver-Id (your resolverId)X-Melee-Api-Key (your apiKey)
Key id headerX-Melee-Key-Id—
Identity token in the stringresolverIdapiKey
toSign = METHOD + " " + path + " " + sha256hex(body) + " " + identity + " " + timestampMillis signature = hex_lowercase( HMAC-SHA256( key = utf8(secret), message = utf8(toSign) ) )
  • METHOD: uppercase HTTP method.
  • path: the request-target path exactly as sent, starting with /, including any path prefix (for callbacks: the path part of your baseUrl plus the endpoint path; for the API: /api/resolver/v1/...), including the query string with its leading ? if one is present, in the exact byte order sent, no re-encoding, no trailing slash normalization. No scheme or host.
  • sha256hex(body): SHA-256 of the raw request body bytes as transmitted, hex lowercase. For a request with no body (every GET) it is the hash of zero bytes: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855.
  • identity: the resolverId UUID string in lowercase, or the apiKey verbatim.
  • timestampMillis: Unix time in milliseconds as a decimal string, identical to the X-Melee-Timestamp header. Accept a skew of at most 5 minutes in either direction. Retries of a callback are re-signed with a fresh timestamp; the X-Melee-Delivery-Id stays the same.
  • Secrets are used as their UTF-8 bytes; they are not base64-decoded.

Vector: callback, POST

callbackSecret = cs_test_9f8e7d6c5b4a resolverId = 5f2c9a1e-3b7d-4c21-9e10-0a1b2c3d4e5f baseUrl = https://resolver.example.com/melee request = POST https://resolver.example.com/melee/lifecycle timestampMillis = 1789000000123 body = {"marketPubkey":"9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin","event":"Live","reason":"TradingStarted"} sha256hex(body) = c91911388cf03d5831d82c0f08170f3773beca24ee6607f7ec69b9885c9cc55d toSign = POST /melee/lifecycle c91911388cf03d5831d82c0f08170f3773beca24ee6607f7ec69b9885c9cc55d 5f2c9a1e-3b7d-4c21-9e10-0a1b2c3d4e5f 1789000000123 X-Melee-Signature = c6f552aca8a1ae8b26260ae8fbb4a94be03e2fa00530b1a9e362ad5385100b7d

Vector: callback, GET

request = GET https://resolver.example.com/melee/status/9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin toSign = GET /melee/status/9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 5f2c9a1e-3b7d-4c21-9e10-0a1b2c3d4e5f 1789000000123 X-Melee-Signature = f605b43c7c3a0338747cc34ac9d9dad307821276e0a4fa05e155a3acc57516dc

Vector: API call, POST

apiKey = mk_test_4d3c2b1a apiSecret = sk_test_0f1e2d3c4b5a request = POST https://api.dev.melee.markets/api/resolver/v1/markets/9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin/resolve timestampMillis = 1789000005000 body = {"outcome":{"outcomeIndex":1},"definitionHash":"9f2a0c7d1b3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c"} sha256hex(body) = 8e15e7cac2b92dfa2131c03a72394903773c033af6d8b78b7a804ff3530d5581 toSign = POST /api/resolver/v1/markets/9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin/resolve 8e15e7cac2b92dfa2131c03a72394903773c033af6d8b78b7a804ff3530d5581 mk_test_4d3c2b1a 1789000005000 X-Melee-Signature = b99bd7fddc9b6bab063835ce11625b3d557ae7078810b56ce576668fbc2a9adc

Verifying a callback (Node.js)

import { createHash, createHmac, timingSafeEqual } from 'node:crypto' export function verifyMeleeCallback({ method, path, rawBody, headers, secretsByKeyId }) { const ts = headers['x-melee-timestamp'] ?? '' if (!/^\d{1,19}$/.test(ts)) return false // Number('') is 0 and Number('abc') is NaN; both must fail if (Math.abs(Date.now() - Number(ts)) > 5 * 60 * 1000) return false const secret = secretsByKeyId[headers['x-melee-key-id']] if (!secret) return false const bodyHash = createHash('sha256').update(rawBody ?? Buffer.alloc(0)).digest('hex') const toSign = `${method.toUpperCase()} ${path} ${bodyHash} ${headers['x-melee-resolver-id']} ${ts}` const expected = createHmac('sha256', secret).update(toSign).digest('hex') const given = headers['x-melee-signature'] ?? '' return given.length === expected.length && timingSafeEqual(Buffer.from(given), Buffer.from(expected)) }

Canonical JSON and the definition hash

definitionHash = sha256hex( JCS(definition) ) where JCS is RFC 8785 : object members sorted by Unicode code point of the key, no insignificant whitespace, strings escaped per JSON with the minimal escapes JCS prescribes, integers serialized without fraction or exponent, null/true/false literal, UTF-8 output. Every field of the definition is always present (see the field table on Market acceptance); every integer is ≤ 2^53−1.

Vector (the example document on the acceptance page; its resolver.resolverAuthority/proposerAuthority are the test key below, which is why the evidence vector signs this hash):

JCS = {"creator":{"wallet":"7Zb1bGi32pfsrBkzWdqd4dFhUzDdeLXbrWijk3wsQwvR"},"description":"","disputable":false,"endDate":1788998400,"marketToken":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","outcomes":[{"index":0,"label":"Yes"},{"index":1,"label":"No"}],"resolver":{"proposerAuthority":"FAe4sisG95oZ42w7buUn5qEE4TAnfTTFPiguZUHmhiF","resolutionFeeRateBps":50,"resolverAuthority":"FAe4sisG95oZ42w7buUn5qEE4TAnfTTFPiguZUHmhiF","resolverId":"5f2c9a1e-3b7d-4c21-9e10-0a1b2c3d4e5f","upFrontFee":10000000,"upFrontFeeMint":"Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB"},"rules":"Resolves YES if X happens before 2026-07-01T00:00:00Z.","schemaVersion":1,"timingPolicy":{"earliestProposal":"marketStart","timeoutOffsetSecs":86400},"title":"Will X happen by June 30?"} hash = 22044a324d9bdc079c809b8c194fdb981e905e1b831f00d2c0178f36f10aa951

JCS libraries: canonicalize (npm), rfc8785 (Python), github.com/gowebpki/jcs (Go), Json.Canonicalization (.NET).

Acceptance evidence

message = utf8( "melee-accept:v1:" + marketPubkey + ":" + definitionHash ) signature = base58( Ed25519_sign_detached( resolverAuthority_secret_key, message ) ) // 64 bytes

Plain Ed25519 over the raw message bytes (nacl.sign.detached, ed25519-dalek sign, Node crypto.sign(null, msg, key)). No Solana off-chain-message prefix, no hashing of the message before signing.

Vector:

resolverAuthority seed (hex) = 000102030405060708090a0b0c0d0e0f101112131415161718191a1b1c1d1e1f resolverAuthority pubkey = FAe4sisG95oZ42w7buUn5qEE4TAnfTTFPiguZUHmhiF marketPubkey = 9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin definitionHash = 22044a324d9bdc079c809b8c194fdb981e905e1b831f00d2c0178f36f10aa951 message = melee-accept:v1:9xQeWvG816bUx9EPjHmaT23yvVM2ZWbrrpZb9PusVFin:22044a324d9bdc079c809b8c194fdb981e905e1b831f00d2c0178f36f10aa951 signature (base58) = 2VNk7TKX1dfL9Zm3hcaSV8te8yS1kbJpbNiGLjrXTBQnouKmqZ9uivqBQidR5nLpoBDJrtsDGwa1yPWBKfT7mzmJ

The seed is a test value only; never use it.

Registration proof

POST /resolvers carries authorityProofs (see Proof of key ownership):

message = utf8( "melee-register:v1:" + network + ":" + sha256hex( JCS( body without authorityProofs ) ) ) // network: devnet signature = base58( Ed25519_sign_detached( resolverAuthority_secret_key, message ) ) // 64 bytes

Vector (the same test key as above, registering on devnet):

body (before adding authorityProofs) {"name":"Example Sports Data","category":"DataFeed","resolverAuthority":"FAe4sisG95oZ42w7buUn5qEE4TAnfTTFPiguZUHmhiF","minConfidenceBps":8000,"disputable":false,"baseUrl":"https://resolver.example.com/melee","trigger":{"type":"EndTime","offsetSecs":900},"issuedAt":1790164800} JCS(body) hash = 78eb8b92706f31ae0b3cad6b6f44ad1af2f608ff48b8298fd3386e8468c1b4af message = melee-register:v1:devnet:78eb8b92706f31ae0b3cad6b6f44ad1af2f608ff48b8298fd3386e8468c1b4af signature (base58) = 3MR29e3gsPzJGE1bcCAKuPF2L2Mzpua5MzCFKf6xDu47uNzBBFum7kZg3eD45nyKSg4TGSNYjdrdmKXQVnQ9dzQA

Code: sign the registration

Copy one of these (TypeScript, Python, or plain terminal), fill in your own fields, and run it. It writes the complete, signed request body to registration.json; send that file as-is to POST /resolvers with an Idempotency-Key (a UUID) header, within 5 minutes (see Proof of key ownership). If you set a separate proposerAuthority, sign the same message with that key too and add it as authorityProofs.proposerAuthority.

Your resolver key is an ordinary Solana keypair. Create a new one with solana-keygen new -o resolver-authority.json; it must never have been used on Melee.

TypeScript / Node (npm install tweetnacl bs58 canonicalize):

import { createHash } from 'node:crypto' import fs from 'node:fs' import nacl from 'tweetnacl' import bs58 from 'bs58' import canonicalize from 'canonicalize' // RFC 8785 (JCS) const keyPair = nacl.sign.keyPair.fromSecretKey( Uint8Array.from(JSON.parse(fs.readFileSync('resolver-authority.json', 'utf8'))), ) const network = 'devnet' const body = { name: 'Example Sports Data', category: 'DataFeed', resolverAuthority: bs58.encode(keyPair.publicKey), minConfidenceBps: 8000, disputable: false, baseUrl: 'https://resolver.example.com/melee', trigger: { type: 'EndTime', offsetSecs: 900 }, issuedAt: Math.floor(Date.now() / 1000), } const hash = createHash('sha256').update(canonicalize(body), 'utf8').digest('hex') const message = `melee-register:v1:${network}:${hash}` const signature = bs58.encode(nacl.sign.detached(new TextEncoder().encode(message), keyPair.secretKey)) const request = { ...body, authorityProofs: { resolverAuthority: signature } } fs.writeFileSync('registration.json', JSON.stringify(request))

Python (pip install pynacl base58 rfc8785):

import hashlib, json, time import base58 import rfc8785 # RFC 8785 (JCS) from nacl.signing import SigningKey seed = bytes(json.load(open("resolver-authority.json")))[:32] # a Solana keypair file: seed first key = SigningKey(seed) network = "devnet" body = { "name": "Example Sports Data", "category": "DataFeed", "resolverAuthority": base58.b58encode(bytes(key.verify_key)).decode(), "minConfidenceBps": 8000, "disputable": False, "baseUrl": "https://resolver.example.com/melee", "trigger": {"type": "EndTime", "offsetSecs": 900}, "issuedAt": int(time.time()), } digest = hashlib.sha256(rfc8785.dumps(body)).hexdigest() message = f"melee-register:v1:{network}:{digest}" signature = base58.b58encode(key.sign(message.encode()).signature).decode() request = {**body, "authorityProofs": {"resolverAuthority": signature}} json.dump(request, open("registration.json", "w"))

Terminal only (bash, no script language): needs jq, bc, xxd and OpenSSL 3. Linux usually has it; on macOS the built-in openssl (LibreSSL) can’t sign Ed25519, so run brew install openssl jq and set OPENSSL=$(brew --prefix openssl@3)/bin/openssl. Paste this into a terminal in the folder with your key file:

set -euo pipefail KEY=resolver-authority.json # Solana keypair file from `solana-keygen new` NETWORK=devnet ISSUED_AT=$(date +%s) # must be within 5 minutes when you send it OPENSSL=${OPENSSL:-openssl} # must be OpenSSL 3; on macOS: OPENSSL=$(brew --prefix openssl@3)/bin/openssl b58() { # hex on stdin -> base58 local hex; hex=$(tr -d '\n' | tr 'a-f' 'A-F'); local ones="" while [[ $hex == 00* ]]; do ones+="1"; hex=${hex:2}; done local alphabet=123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz out="" if [[ -n $hex ]]; then for d in $(echo "obase=58; ibase=16; $hex" | BC_LINE_LENGTH=0 bc); do out+=${alphabet:$((10#$d)):1}; done fi printf '%s%s' "$ones" "$out" } SEED_HEX=$(jq -r '.[0:32][]' "$KEY" | xargs printf '%02x') PUBKEY=$(jq -r '.[32:64][]' "$KEY" | xargs printf '%02x' | b58) jq -n --arg auth "$PUBKEY" --argjson issuedAt "$ISSUED_AT" '{ name: "Example Sports Data", category: "DataFeed", resolverAuthority: $auth, minConfidenceBps: 8000, disputable: false, baseUrl: "https://resolver.example.com/melee", trigger: { type: "EndTime", offsetSecs: 900 }, issuedAt: $issuedAt }' > body.json HASH=$(jq -cjS . body.json | shasum -a 256 | cut -d' ' -f1) # canonical JSON (sorted, compact), then SHA-256 MESSAGE="melee-register:v1:$NETWORK:$HASH" { echo "-----BEGIN PRIVATE KEY-----" echo "302e020100300506032b657004220420$SEED_HEX" | xxd -r -p | base64 echo "-----END PRIVATE KEY-----"; } > key.pem printf '%s' "$MESSAGE" > message.txt SIGNATURE=$("$OPENSSL" pkeyutl -sign -rawin -inkey key.pem -in message.txt | xxd -p | b58) rm -f key.pem message.txt jq --arg sig "$SIGNATURE" '. + {authorityProofs: {resolverAuthority: $sig}}' body.json > registration.json rm -f body.json echo "Signed: $MESSAGE"

Optional self-check of your code (not a request to send). Temporarily use the test seed above as the key and set issuedAt to the vector’s fixed value 1790164800; your code must then print exactly the vector’s hash and signature. 1790164800 exists only so the vector is reproducible. A real request must carry the current time, and the API refuses this old value with proof_expired. If Melee answers proof_invalid for a real request, its message quotes the exact string it expected you to sign; compare it with yours.

Credential claim proof

POST /resolvers/credentials/claim (see Credential revocation and reclaim) carries authorityProofs built exactly like the registration proof, with its own prefix:

message = utf8( "melee-claim-credentials:v1:" + network + ":" + sha256hex( JCS( body without authorityProofs ) ) ) // network: devnet signature = base58( Ed25519_sign_detached( registered_authority_secret_key, message ) ) // 64 bytes

Sign with the resolverAuthority Melee has on record, and with the registered proposerAuthority when it is a different key; keys named in the request are never used. issuedAt must be within 5 minutes of Melee’s clock and later than the issuedAt of your last claim. The separate prefix means a registration proof can never claim credentials and a claim proof can never register. To sign a claim with one of the registration scripts, replace the body with { apiKey, issuedAt } and the prefix melee-register:v1: with melee-claim-credentials:v1:; there is no Idempotency-Key.

Vector (the test key from Acceptance evidence, claiming on devnet):

body (before adding authorityProofs) {"apiKey":"mk_test_5f2c9a1e0b7d4c3e9a8f6b5d4c3e2a1f","issuedAt":1790164800} JCS(body) hash = 28f3dbd932472bb8ffa928b9821fe0c8146b13f5a4676dddb22f58132c717095 message = melee-claim-credentials:v1:devnet:28f3dbd932472bb8ffa928b9821fe0c8146b13f5a4676dddb22f58132c717095 signature (base58) = 3x2MCfjMcnnd7ZmgkXsJRMbWj1zmu64MbjMTJ5iduwaJAAn7iHbsE8tutHocnSL629BEgfe5GRmGNYgGgrrmt94b

Deriving outcome addresses

outcome_i = findProgramAddress( seeds = [ utf8("outcome"), bytes32(marketPubkey), [i] ], programId )

bytes32(marketPubkey) is the base58-decoded 32-byte key; [i] is one byte, the outcome index (0–7). programId must come from GET /platform/programs (or be validated against it).

import { PublicKey } from '@solana/web3.js' export function outcomeAddress(marketPubkey, index, programId) { const [pda] = PublicKey.findProgramAddressSync( [Buffer.from('outcome'), new PublicKey(marketPubkey).toBuffer(), Buffer.from([index])], new PublicKey(programId), ) return pda } export function outcomeSetHash(outcomePubkeys) { const h = createHash('sha256') for (const k of outcomePubkeys) h.update(new PublicKey(k).toBuffer()) return h.digest('hex') }

outcomeSetHash is hex lowercase over the concatenated raw keys in index order, covering every outcome of the market. Read accounts at confirmed commitment; confirm each is owned by programId and that the account for index n (one past the last accepted outcome) does not exist.

For reference, the market account itself is findProgramAddress([utf8("market"), u64le(marketId)], programId) where marketId is the decimal string in payloads parsed as an unsigned 64-bit little-endian integer. You do not need to derive it; it is always given as marketPubkey.

Signing transactions

Every envelope’s transaction is a base64 Solana v0 VersionedTransaction. Melee may have already placed its own signatures in it (registration, sponsored cases). Rules:

  1. Decode: VersionedTransaction.deserialize(Buffer.from(transaction, 'base64')).
  2. Do not modify the message. Any change invalidates Melee’s signatures and the submission is rejected with transaction_altered.
  3. Sign with each of your keys listed in signers with signed: false: tx.sign([keypair]) adds a signature at that key’s index and leaves other signatures intact.
  4. Re-encode: Buffer.from(tx.serialize()).toString('base64') and submit via POST /transactions/{transactionId} before expiresAt.

Before signing, check what you are signing. The message must satisfy all of:

  • every instruction’s program id is one of: a Melee program from GET /platform/programs, the System program, the SPL Token or Token-2022 program, the Associated Token Account program, the Compute Budget program, or the SPL Memo program;
  • your resolverAuthority/proposerAuthority appear only as signers of Melee program instructions, never as the authority of a token transfer;
  • the fee payer is the payer you requested (or one you accepted as sponsored).

Melee’s envelopes are constructed so these hold; the check protects you against a compromised channel. Address lookup tables may be used; if you simulate before signing, resolve them with your RPC.

Envelopes expire about 25 seconds after issue, before their recent blockhash does. Sign and submit promptly. Melee does not use durable nonces.

Contract versions

Melee’s markets program has versions, and more than one can be live on a network at the same time (Program ids). A market stays on the program it was created on for its whole life, and what you can do on it follows that program.

When Melee deploys a new program version, it registers every activated resolver there itself, at its own cost: you sign and pay nothing, and your credentials, record and existing markets don’t change. Until that has run for you, creators can’t select you for markets on the new program. If one of your keys already holds a different Melee user account on the new program, Melee leaves it as it is and you stay unregistered there.

The program new markets use today (devnet 5xZenqSrpGjmCYzCrcKYK3if4U2fPr9q4mVNmGWApZou, contract line v3.0) predates some resolver features:

AreaOn the current program
Resolution feesNot available. POST /markets/{market}/claim-fees and PUT /markets/{market}/fee-recipient answer 501 feature_unavailable. Markets carry a resolution fee rate of 0, and GET /platform/limits reports resolutionFeeRateBps as 0–0. Registration still accepts your resolutionFeeRateBps within the configured range and stores it.
Up-front feesNot charged: markets carry an up-front fee of 0. Your upFrontFees are stored.
Void before earliestProposalTsNot possible. void and a void proposal answer 409 not_yet_open with opensAt until then.
earliestProposalTs10 minutes after the market’s planned trading start, as on any program, but at most 7 days before timeoutTs, the longest the program allows between the two. For a market whose timeoutTs is further out, the window opens at timeoutTs − 7 days, so you can’t propose, resolve or void it before then. Always use the value in live, the Live lifecycle event and every market payload.

Enumerations

NameValues
ResolverCategoryDataFeed, Oracle, Authority
ResolverStatePendingActivation, Active, Unhealthy, Suspended, Retired
credentials.statusactive, revoked, claimable
TriggerTypeEndTime, Creator, None
ResolutionStatus (yours)Pending, Resolving, Dispute, Resolved
DisplayStatus (Melee’s)Pending, Resolving, Dispute, Resolved, Voided, Cancelled, Failed, Unknown
onChain.stateInitialized, Pending, Presale, Live, Arbitration, Resolved, Failed, Cancelled, Closed, Voided
changeTypeCreation, TitleDescription, OutcomeLabel, OutcomeAdd, EndDate, TimingPolicy, RulesEdit, RulesRequest, AuthorityChange
proposedByCreator, Resolver, Melee
signers[].roleresolver, proposer, payer, feeRecipient, melee
unavailableReasonmarket_not_active, presale_book_frozen, no_liquidity, unknown
Lifecycle eventLive, Cancelled, Failed, Voided, Resolved, AuthorityChanged
platformVoidReasonAuthorityDrift, DefinitionDrift, Operator
Change statusApplied, Received, Accepted, Declined, Proposed, Rejected, Failed (meanings)
Proposal statusEvaluating, Evaluated, BelowThreshold, Accepted, Rejected, Cancelled, Expired, Created
Transaction statusPending, Submitted, Confirmed, Failed, Expired

Melee may add platformVoidReason values; treat a value you do not recognize as a generic platform void.

Field bounds

Current values; the source of truth is GET /platform/limits.

FieldBound
title≤ 200 chars
description≤ 2000 chars
rules≤ 2400 chars
resolver rulesGuidelines≤ 4000 chars; no links; Melee may reject later (details)
outcome label≤ 64 chars; 2–8 outcomes
notes, rationale, reason≤ 500 chars
status message≤ 280 chars
minConfidenceBps1–10000
trigger.offsetSecs−604800 to +43200
integers in the definition≤ 2^53−1
Last updated on