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) | |
|---|---|---|
| Secret | callbackSecret | apiSecret |
| Identity header | X-Melee-Resolver-Id (your resolverId) | X-Melee-Api-Key (your apiKey) |
| Key id header | X-Melee-Key-Id | — |
| Identity token in the string | resolverId | apiKey |
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 yourbaseUrlplus 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: theresolverIdUUID string in lowercase, or theapiKeyverbatim.timestampMillis: Unix time in milliseconds as a decimal string, identical to theX-Melee-Timestampheader. Accept a skew of at most 5 minutes in either direction. Retries of a callback are re-signed with a fresh timestamp; theX-Melee-Delivery-Idstays 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 = c6f552aca8a1ae8b26260ae8fbb4a94be03e2fa00530b1a9e362ad5385100b7dVector: 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 = f605b43c7c3a0338747cc34ac9d9dad307821276e0a4fa05e155a3acc57516dcVector: 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 = b99bd7fddc9b6bab063835ce11625b3d557ae7078810b56ce576668fbc2a9adcVerifying 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 = 22044a324d9bdc079c809b8c194fdb981e905e1b831f00d2c0178f36f10aa951JCS 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 bytesPlain 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) = 2VNk7TKX1dfL9Zm3hcaSV8te8yS1kbJpbNiGLjrXTBQnouKmqZ9uivqBQidR5nLpoBDJrtsDGwa1yPWBKfT7mzmJThe 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 bytesVector (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) = 3MR29e3gsPzJGE1bcCAKuPF2L2Mzpua5MzCFKf6xDu47uNzBBFum7kZg3eD45nyKSg4TGSNYjdrdmKXQVnQ9dzQACode: 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 bytesSign 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) = 3x2MCfjMcnnd7ZmgkXsJRMbWj1zmu64MbjMTJ5iduwaJAAn7iHbsE8tutHocnSL629BEgfe5GRmGNYgGgrrmt94bDeriving 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:
- Decode:
VersionedTransaction.deserialize(Buffer.from(transaction, 'base64')). - Do not modify the message. Any change invalidates Melee’s signatures and the submission is rejected with
transaction_altered. - Sign with each of your keys listed in
signerswithsigned: false:tx.sign([keypair])adds a signature at that key’s index and leaves other signatures intact. - Re-encode:
Buffer.from(tx.serialize()).toString('base64')and submit viaPOST /transactions/{transactionId}beforeexpiresAt.
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/proposerAuthorityappear only as signers of Melee program instructions, never as the authority of a token transfer; - the fee payer is the
payeryou 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:
| Area | On the current program |
|---|---|
| Resolution fees | Not 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 fees | Not charged: markets carry an up-front fee of 0. Your upFrontFees are stored. |
Void before earliestProposalTs | Not possible. void and a void proposal answer 409 not_yet_open with opensAt until then. |
earliestProposalTs | 10 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
| Name | Values |
|---|---|
ResolverCategory | DataFeed, Oracle, Authority |
ResolverState | PendingActivation, Active, Unhealthy, Suspended, Retired |
credentials.status | active, revoked, claimable |
TriggerType | EndTime, Creator, None |
ResolutionStatus (yours) | Pending, Resolving, Dispute, Resolved |
DisplayStatus (Melee’s) | Pending, Resolving, Dispute, Resolved, Voided, Cancelled, Failed, Unknown |
onChain.state | Initialized, Pending, Presale, Live, Arbitration, Resolved, Failed, Cancelled, Closed, Voided |
changeType | Creation, TitleDescription, OutcomeLabel, OutcomeAdd, EndDate, TimingPolicy, RulesEdit, RulesRequest, AuthorityChange |
proposedBy | Creator, Resolver, Melee |
signers[].role | resolver, proposer, payer, feeRecipient, melee |
unavailableReason | market_not_active, presale_book_frozen, no_liquidity, unknown |
Lifecycle event | Live, Cancelled, Failed, Voided, Resolved, AuthorityChanged |
platformVoidReason | AuthorityDrift, DefinitionDrift, Operator |
Change status | Applied, Received, Accepted, Declined, Proposed, Rejected, Failed (meanings) |
Proposal status | Evaluating, Evaluated, BelowThreshold, Accepted, Rejected, Cancelled, Expired, Created |
Transaction status | Pending, 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.
| Field | Bound |
|---|---|
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 |
minConfidenceBps | 1–10000 |
trigger.offsetSecs | −604800 to +43200 |
| integers in the definition | ≤ 2^53−1 |