> For the complete documentation index, see [llms.txt](https://docs.decentraland.org/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.decentraland.org/apis/apis/rewards/rewards.md).

# Rewards

Reward management operations

## Get user rewards

> Retrieve rewards for the authenticated user with optional filtering

```json
{"openapi":"3.0.3","info":{"title":"Decentraland Referral Service API","version":"1.0.0"},"tags":[{"name":"Rewards","description":"Reward management operations"}],"servers":[{"url":"https://rewards.decentraland.org","description":"Production server"},{"url":"https://rewards.decentraland.zone","description":"Development server"},{"url":"http://localhost:8000","description":"Local Development server"}],"security":[],"paths":{"/api/rewards":{"get":{"tags":["Rewards"],"summary":"Get user rewards","description":"Retrieve rewards for the authenticated user with optional filtering","parameters":[{"name":"status","in":"query","description":"Filter rewards by status","schema":{"type":"string","enum":["assigned","sending","success","rejected","unassigned","pending","available","claimed","successful","failed","confirmed"]}},{"name":"limit","in":"query","description":"Maximum number of results per request","schema":{"type":"string","default":"100"}},{"name":"offset","in":"query","description":"Number of results to skip","schema":{"type":"string","default":"0"}}],"responses":{"200":{"description":"List of rewards","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","required":["id","campaign_id","user","status","chain_id","target","value","token","airdrop_type","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Reward ID"},"campaign_id":{"type":"string","format":"uuid","description":"Campaign ID"},"campaign_key":{"type":"string","format":"uuid","nullable":true,"description":"Campaign Key ID"},"user":{"type":"string","format":"address","nullable":true,"description":"User address assigned to this reward"},"status":{"type":"string","enum":["unassigned","pending","assigned","sending","success","rejected","confirmed","available","claimed","successful","failed"],"description":"Reward delivery status"},"chain_id":{"type":"string","enum":["1","3","4","5","42","137","80001","80002","11155111"],"description":"Blockchain chain ID"},"transaction_hash":{"type":"string","nullable":true,"description":"Hash of the transaction in which the reward was sent"},"block_number":{"type":"integer","nullable":true,"description":"Block number of the transaction"},"airdrop_type":{"type":"string","enum":["None","ERC20Transfer","ERC721Mint","ERC721Transfer","ERC721Kitty","CollectionV2IssueToken"],"description":"Delivery strategy for the reward"},"target":{"type":"string","format":"address","description":"Target contract for the reward"},"value":{"type":"string","description":"Value in the contract for the reward"},"priority":{"type":"number","description":"Assignment priority for the reward"},"group":{"type":"string","nullable":true,"description":"Assignment group for the reward"},"token":{"type":"string","description":"Human-readable name for the reward"},"image":{"type":"string","format":"uri","nullable":true,"description":"Image that visually represents this reward"},"rarity":{"type":"string","enum":["common","uncommon","rare","epic","legendary","mythic","unique"],"description":"Item rarity"},"category":{"type":"string","enum":["eyebrows","eyes","facial_hair","hair","mouth","upper_body","lower_body","feet","earring","eyewear","hat","helmet","mask","tiara","top_head","dance","stunt","greeting","fun","poses","reactions","horror","miscellaneous"],"description":"Item category"},"from_referral":{"type":"string","format":"address","nullable":true,"description":"Address of the user who referred this reward"},"payload":{"type":"string","nullable":true,"description":"Transaction payload (L1 only)"},"signature":{"type":"string","nullable":true,"description":"Transaction signature (L1 only)"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"Reward expiration time (L1 only)"},"created_at":{"type":"string","format":"date-time","description":"The time the reward was created"},"updated_at":{"type":"string","format":"date-time","description":"The time the reward was last updated"},"assigned_at":{"type":"string","format":"date-time","nullable":true,"description":"The time the reward was assigned"}}}},"total":{"type":"number","description":"Total number of rewards matching the filter"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","description":"Whether the request was successful"},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"data":{"type":"object","description":"Additional error data"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","description":"Whether the request was successful"},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"data":{"type":"object","description":"Additional error data"}}}}}}}}}}}
```

## Assign reward

> Assign a reward to a user using a campaign key

```json
{"openapi":"3.0.3","info":{"title":"Decentraland Referral Service API","version":"1.0.0"},"tags":[{"name":"Rewards","description":"Reward management operations"}],"servers":[{"url":"https://rewards.decentraland.org","description":"Production server"},{"url":"https://rewards.decentraland.zone","description":"Development server"},{"url":"http://localhost:8000","description":"Local Development server"}],"security":[],"paths":{"/api/rewards":{"post":{"tags":["Rewards"],"summary":"Assign reward","description":"Assign a reward to a user using a campaign key","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["campaign_key"],"properties":{"campaign_key":{"type":"string","description":"Campaign key","minLength":1},"beneficiary":{"type":"string","format":"address","description":"User address to assign the reward to"},"captcha_id":{"type":"string","format":"uuid","description":"Captcha identifier"},"captcha_value":{"type":"string","description":"Captcha value","minLength":6,"maxLength":6},"catalyst":{"type":"string","format":"uri","description":"Catalyst URL where the user is connected"},"assign_target":{"type":"string","format":"address","description":"Target contract for reward assignment"},"assign_value":{"type":"string","description":"Value for reward assignment","minLength":1},"assign_group":{"type":"string","description":"Group for reward assignment","minLength":1}}}}}},"responses":{"200":{"description":"Reward assigned successfully","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"array","items":{"type":"object","required":["id","campaign_id","user","status","chain_id","target","value","token","airdrop_type","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Reward ID"},"campaign_id":{"type":"string","format":"uuid","description":"Campaign ID"},"campaign_key":{"type":"string","format":"uuid","nullable":true,"description":"Campaign Key ID"},"user":{"type":"string","format":"address","nullable":true,"description":"User address assigned to this reward"},"status":{"type":"string","enum":["unassigned","pending","assigned","sending","success","rejected","confirmed","available","claimed","successful","failed"],"description":"Reward delivery status"},"chain_id":{"type":"string","enum":["1","3","4","5","42","137","80001","80002","11155111"],"description":"Blockchain chain ID"},"transaction_hash":{"type":"string","nullable":true,"description":"Hash of the transaction in which the reward was sent"},"block_number":{"type":"integer","nullable":true,"description":"Block number of the transaction"},"airdrop_type":{"type":"string","enum":["None","ERC20Transfer","ERC721Mint","ERC721Transfer","ERC721Kitty","CollectionV2IssueToken"],"description":"Delivery strategy for the reward"},"target":{"type":"string","format":"address","description":"Target contract for the reward"},"value":{"type":"string","description":"Value in the contract for the reward"},"priority":{"type":"number","description":"Assignment priority for the reward"},"group":{"type":"string","nullable":true,"description":"Assignment group for the reward"},"token":{"type":"string","description":"Human-readable name for the reward"},"image":{"type":"string","format":"uri","nullable":true,"description":"Image that visually represents this reward"},"rarity":{"type":"string","enum":["common","uncommon","rare","epic","legendary","mythic","unique"],"description":"Item rarity"},"category":{"type":"string","enum":["eyebrows","eyes","facial_hair","hair","mouth","upper_body","lower_body","feet","earring","eyewear","hat","helmet","mask","tiara","top_head","dance","stunt","greeting","fun","poses","reactions","horror","miscellaneous"],"description":"Item category"},"from_referral":{"type":"string","format":"address","nullable":true,"description":"Address of the user who referred this reward"},"payload":{"type":"string","nullable":true,"description":"Transaction payload (L1 only)"},"signature":{"type":"string","nullable":true,"description":"Transaction signature (L1 only)"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"Reward expiration time (L1 only)"},"created_at":{"type":"string","format":"date-time","description":"The time the reward was created"},"updated_at":{"type":"string","format":"date-time","description":"The time the reward was last updated"},"assigned_at":{"type":"string","format":"date-time","nullable":true,"description":"The time the reward was assigned"}}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","description":"Whether the request was successful"},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"data":{"type":"object","description":"Additional error data"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","description":"Whether the request was successful"},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"data":{"type":"object","description":"Additional error data"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","description":"Whether the request was successful"},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"data":{"type":"object","description":"Additional error data"}}}}}}}}}}}
```

## Get reward details

> Retrieve detailed information about a specific reward

```json
{"openapi":"3.0.3","info":{"title":"Decentraland Referral Service API","version":"1.0.0"},"tags":[{"name":"Rewards","description":"Reward management operations"}],"servers":[{"url":"https://rewards.decentraland.org","description":"Production server"},{"url":"https://rewards.decentraland.zone","description":"Development server"},{"url":"http://localhost:8000","description":"Local Development server"}],"security":[],"paths":{"/api/rewards/{reward_id}":{"get":{"tags":["Rewards"],"summary":"Get reward details","description":"Retrieve detailed information about a specific reward","parameters":[{"name":"reward_id","in":"path","required":true,"description":"Reward ID","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Reward details","content":{"application/json":{"schema":{"type":"object","properties":{"ok":{"type":"boolean"},"data":{"type":"object","required":["id","campaign_id","user","status","chain_id","target","value","token","airdrop_type","created_at","updated_at"],"properties":{"id":{"type":"string","format":"uuid","description":"Reward ID"},"campaign_id":{"type":"string","format":"uuid","description":"Campaign ID"},"campaign_key":{"type":"string","format":"uuid","nullable":true,"description":"Campaign Key ID"},"user":{"type":"string","format":"address","nullable":true,"description":"User address assigned to this reward"},"status":{"type":"string","enum":["unassigned","pending","assigned","sending","success","rejected","confirmed","available","claimed","successful","failed"],"description":"Reward delivery status"},"chain_id":{"type":"string","enum":["1","3","4","5","42","137","80001","80002","11155111"],"description":"Blockchain chain ID"},"transaction_hash":{"type":"string","nullable":true,"description":"Hash of the transaction in which the reward was sent"},"block_number":{"type":"integer","nullable":true,"description":"Block number of the transaction"},"airdrop_type":{"type":"string","enum":["None","ERC20Transfer","ERC721Mint","ERC721Transfer","ERC721Kitty","CollectionV2IssueToken"],"description":"Delivery strategy for the reward"},"target":{"type":"string","format":"address","description":"Target contract for the reward"},"value":{"type":"string","description":"Value in the contract for the reward"},"priority":{"type":"number","description":"Assignment priority for the reward"},"group":{"type":"string","nullable":true,"description":"Assignment group for the reward"},"token":{"type":"string","description":"Human-readable name for the reward"},"image":{"type":"string","format":"uri","nullable":true,"description":"Image that visually represents this reward"},"rarity":{"type":"string","enum":["common","uncommon","rare","epic","legendary","mythic","unique"],"description":"Item rarity"},"category":{"type":"string","enum":["eyebrows","eyes","facial_hair","hair","mouth","upper_body","lower_body","feet","earring","eyewear","hat","helmet","mask","tiara","top_head","dance","stunt","greeting","fun","poses","reactions","horror","miscellaneous"],"description":"Item category"},"from_referral":{"type":"string","format":"address","nullable":true,"description":"Address of the user who referred this reward"},"payload":{"type":"string","nullable":true,"description":"Transaction payload (L1 only)"},"signature":{"type":"string","nullable":true,"description":"Transaction signature (L1 only)"},"expires_at":{"type":"string","format":"date-time","nullable":true,"description":"Reward expiration time (L1 only)"},"created_at":{"type":"string","format":"date-time","description":"The time the reward was created"},"updated_at":{"type":"string","format":"date-time","description":"The time the reward was last updated"},"assigned_at":{"type":"string","format":"date-time","nullable":true,"description":"The time the reward was assigned"}}}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","description":"Whether the request was successful"},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"data":{"type":"object","description":"Additional error data"}}}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","description":"Whether the request was successful"},"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"data":{"type":"object","description":"Additional error data"}}}}}}}}}}}
```


---

# 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:

```
GET https://docs.decentraland.org/apis/apis/rewards/rewards.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.