How to Add a Verifiable Leaderboard with the RankFuel API

This walkthrough takes a leaderboard from creation to a settled, verifiable result using the RankFuel REST API. Every call goes to https://api.rnkfl.com with Authorization: Bearer $RANKFUEL_KEY; get a key from your Rewards Fuel dashboard at app.rewardsfuel.com/rankfuel. Responses use the envelope { "ok": true, "data": …, "error": null }.

1. Create a leaderboard

curl -X POST https://api.rnkfl.com/v1/leaderboards \
  -H "Authorization: Bearer $RANKFUEL_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Spring Long Drive", "slug": "spring-long-drive",
        "sort": "desc", "agg": "best", "tiebreak": "earliest" }'

sort is desc (higher is better) by default, agg decides how repeat scores count (default best), and tiebreak defaults to earliest. Creating the leaderboard also opens its first period. The response includes data.period.id (keep it as $PERIOD_ID) and data.period.commitHash, the commitment you can publish straight away.

2. Submit scores

curl -X POST https://api.rnkfl.com/v1/leaderboards/spring-long-drive/scores \
  -H "Authorization: Bearer $RANKFUEL_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{ "subjectId": "player_42", "subjectLabel": "Rob", "value": 312 }'

Always send an Idempotency-Key. If the network drops and you retry with the same key, the score is not counted twice. subjectId is your stable id for the player or team; subjectLabel is what the board shows. Scores need an open period; after a period closes you get a PERIOD_CLOSED error.

3. Read the rankings

curl https://api.rnkfl.com/v1/leaderboards/spring-long-drive/rankings \
  -H "Authorization: Bearer $RANKFUEL_KEY"

Rankings are cached briefly at the edge, so this is cheap to poll for a live board. To show the board on a site, use a themed embed from the dashboard instead of building your own table.

4. Close the period

curl -X POST https://api.rnkfl.com/v1/periods/$PERIOD_ID/close \
  -H "Authorization: Bearer $RANKFUEL_KEY"

Closing stops new scores and locks the period to a future drand round. Nobody knows that round's randomness yet, which is the point.

5. Settle and publish the proof

curl -X POST https://api.rnkfl.com/v1/periods/$PERIOD_ID/settle \
  -H "Authorization: Bearer $RANKFUEL_KEY"

Once the drand round has been published, settling fetches it, reveals the period secret, derives the seed and writes a proof bundle. Then anyone you share it with can check it:

curl https://api.rnkfl.com/v1/periods/$PERIOD_ID/proof \
  -H "Authorization: Bearer $RANKFUEL_KEY"    # the bundle
curl https://api.rnkfl.com/v1/periods/$PERIOD_ID/verify \
  -H "Authorization: Bearer $RANKFUEL_KEY"    # recomputes commitment + seed

These calls need a RankFuel API key. For a public leaderboard, any key holder with the period id can fetch the proof; private leaderboards keep it to the owner. The bundle itself contains everything needed to recompute the checks by hand.

Try it before you have a key

Public demo boards need no auth: GET https://api.rnkfl.com/v1/public/demos lists them and GET https://api.rnkfl.com/v1/public/demos/golf-long-drive/rankings returns live standings with the same shape as a real board. Agents can call GET https://api.rnkfl.com/v1/public/mcp-discovery for the tool list.

Next steps

• Let an AI agent do the same through MCP: verify before you pay out.
• Pay out prizes with Rewards Fuel, or run a random prize draw with a public proof on RFWIN.