> For the complete documentation index, see [llms.txt](https://docs.fyuz.fun/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.fyuz.fun/api-reference/rewards-and-engagement.md).

# Rewards & Engagement

Quests, referrals, seasons, kings history, airdrop weight and the watchlist.

## Rewards Hub state

> Quest progress, daily streak, achievements and point totals for a wallet.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/rewards/{address}":{"get":{"tags":["Rewards & Engagement"],"summary":"Rewards Hub state","description":"Quest progress, daily streak, achievements and point totals for a wallet.","operationId":"getRewards","parameters":[{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"Rewards state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"parameters":{"address":{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Wallet or token address (hex)."}}}}
```

## 🔏 Claim a quest

> Claims a completed quest for the wallet. Wallet-signed.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/rewards/{address}/claim/{questKey}":{"post":{"tags":["Rewards & Engagement"],"summary":"🔏 Claim a quest","description":"Claims a completed quest for the wallet. Wallet-signed.","operationId":"claimQuest","parameters":[{"$ref":"#/components/parameters/address"},{"name":"questKey","in":"path","required":true,"schema":{"type":"string","enum":["first_buy","launch_token","refer_trader","daily_trade","daily_volume"]}}],"requestBody":{"$ref":"#/components/requestBodies/Signed"},"responses":{"200":{"description":"Points granted."}}}}},"components":{"parameters":{"address":{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Wallet or token address (hex)."}},"requestBodies":{"Signed":{"description":"Wallet-signed action payload.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","message","signature"],"properties":{"address":{"type":"string","description":"Acting wallet."},"message":{"type":"string","description":"The signed message (includes a timestamp for replay protection)."},"signature":{"type":"string","description":"Signature of the message by the wallet."}}}}}}}}}
```

## Referral stats

> Personal referral link stats and the list of referred traders.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/referrals/{address}":{"get":{"tags":["Rewards & Engagement"],"summary":"Referral stats","description":"Personal referral link stats and the list of referred traders.","operationId":"getReferrals","parameters":[{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"Referral state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"parameters":{"address":{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Wallet or token address (hex)."}}}}
```

## GET /referrals/leaderboard

> Referral leaderboard

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/referrals/leaderboard":{"get":{"tags":["Rewards & Engagement"],"summary":"Referral leaderboard","operationId":"referralLeaderboard","responses":{"200":{"description":"Top referrers.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}}
```

## Current season

> Season window, live countdown, prize pot and standings.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/season":{"get":{"tags":["Rewards & Engagement"],"summary":"Current season","description":"Season window, live countdown, prize pot and standings.","operationId":"getSeason","responses":{"200":{"description":"Season state.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}}}
```

## Hall of Champions

> Every King of the Hill reign — token, start, end and duration.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/kings/history":{"get":{"tags":["Rewards & Engagement"],"summary":"Hall of Champions","description":"Every King of the Hill reign — token, start, end and duration.","operationId":"kingsHistory","responses":{"200":{"description":"Reign history.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}}
```

## Airdrop weight

> A wallet's points, rank and projected share of the total allocation weight.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/airdrop/{address}":{"get":{"tags":["Rewards & Engagement"],"summary":"Airdrop weight","description":"A wallet's points, rank and projected share of the total allocation weight.","operationId":"getAirdrop","parameters":[{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"Allocation weight.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}}},"components":{"parameters":{"address":{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Wallet or token address (hex)."}}}}
```

## Watchlist

> The tokens a wallet has starred.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/watchlist/{address}":{"get":{"tags":["Rewards & Engagement"],"summary":"Watchlist","description":"The tokens a wallet has starred.","operationId":"getWatchlist","parameters":[{"$ref":"#/components/parameters/address"}],"responses":{"200":{"description":"Starred tokens.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Token"}}}}}}}}},"components":{"parameters":{"address":{"name":"address","in":"path","required":true,"schema":{"type":"string"},"description":"Wallet or token address (hex)."}},"schemas":{"Token":{"type":"object","properties":{"address":{"type":"string"},"network":{"type":"string"},"name":{"type":"string"},"symbol":{"type":"string"},"description":{"type":"string"},"image":{"type":"string","description":"The fused character image."},"creator":{"type":"string"},"price":{"type":"number"},"marketcap":{"type":"number"},"graduationPercent":{"type":"number"},"launched":{"type":"boolean","description":"True once graduated to PancakeSwap."},"isLive":{"type":"boolean","description":"True while the creator is streaming."},"createdAt":{"type":"string"}}}}}}
```

## POST /watchlist/toggle

> 🔏 Star / unstar a token

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/watchlist/toggle":{"post":{"tags":["Rewards & Engagement"],"summary":"🔏 Star / unstar a token","operationId":"toggleWatchlist","requestBody":{"$ref":"#/components/requestBodies/Signed"},"responses":{"200":{"description":"New watchlist state."}}}}},"components":{"requestBodies":{"Signed":{"description":"Wallet-signed action payload.","required":true,"content":{"application/json":{"schema":{"type":"object","required":["address","message","signature"],"properties":{"address":{"type":"string","description":"Acting wallet."},"message":{"type":"string","description":"The signed message (includes a timestamp for replay protection)."},"signature":{"type":"string","description":"Signature of the message by the wallet."}}}}}}}}}
```

## Distributor payout rounds

> On-chain rewards distributor — historical payout rounds funded by the 0.3% rewards fee stream.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/distributor/rounds":{"get":{"tags":["Rewards & Engagement"],"summary":"Distributor payout rounds","description":"On-chain rewards distributor — historical payout rounds funded by the 0.3% rewards fee stream.","operationId":"distributorRounds","responses":{"200":{"description":"Rounds.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}}
```

## Distributor shares

> Per-wallet shares in the current distribution round.

```json
{"openapi":"3.1.0","info":{"title":"Fyuz API","version":"1.0.0"},"tags":[{"name":"Rewards & Engagement","description":"Quests, referrals, seasons, kings history, airdrop weight and the watchlist."}],"servers":[{"url":"https://api.fyuz.fun","description":"Production"}],"paths":{"/distributor/shares":{"get":{"tags":["Rewards & Engagement"],"summary":"Distributor shares","description":"Per-wallet shares in the current distribution round.","operationId":"distributorShares","responses":{"200":{"description":"Shares.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","additionalProperties":true}}}}}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.fyuz.fun/api-reference/rewards-and-engagement.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.