> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paxos.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Rewards Engine
> Automate tracking, calculation, and distribution of rewards for Paxos-issued stablecoins.
The Rewards Engine automates tracking, calculation, and distribution of custody rewards for Paxos-issued stablecoins. You can interact through the Paxos Dashboard, the API, or both.
## How It Works
Rewards flow through six stages:
```mermaid theme={null}
graph LR
classDef step fill:#e6f7ed,stroke:#16a34a,stroke-width:2px,color:#15803d
classDef auto fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#92400e
A["Create\npayout group"]:::step
B["Register\nreward addresses"]:::step
C["Daily balance\nsnapshot"]:::auto
D["Rewards\ncalculation"]:::auto
E["Automated\npayout"]:::auto
F["Reporting\nvia API"]:::step
A --> B --> C --> D --> E --> F
```
## Key Concepts
| Concept | Description |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Reward address** | A blockchain address submitted for monitoring. Daily balance snapshots determine the rewards earned. |
| **Payout group** | A collection of reward addresses that accumulate rewards collectively and pay out to a single destination address. Payout groups are chain- and jurisdiction-specific. |
| **Claim schedule** | Defines when and how your organization receives reward payouts. |
| **Claim** | A single reward payout event generated according to a claim schedule. |
| **Jurisdiction** | Each payout group carries an EU or non-EU designation that maps to the applicable contractual earnings rate. |
### On-chain vs Off-chain Rewards
The Rewards Engine supports two payout modes. Understanding which applies to your integration determines how claims are executed.
| Mode | How rewards are calculated | How payouts are executed |
| ------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| **Off-chain** | Paxos calculates rewards based on daily balance snapshots | Paxos executes the payout directly — no signing required |
| **On-chain** | Rewards accumulate daily in a smart contract on an EVM chain | The `claimer_address` signs and submits the claim transaction directly to the contract |
The mode is determined by the blockchain and asset combination — your account configuration specifies which applies to each payout group.
**Plan around these constraints before integrating.**
* Claims run on a claim schedule you configure (daily, weekly, or monthly) — manual triggers are not available today.
* No retroactive claims. Wallets only accrue rewards once they reach `ACTIVE` status — submission alone is not the start of accrual.
* Reward addresses must be assigned to a payout group and reach `ACTIVE` status to accrue rewards.
* Payout groups are chain-specific. Create a separate group for each blockchain you hold stablecoins on.
## Prerequisites
### Authentication
You need a bearer token. See [Authenticate](/guides/developer/authenticate) for setup instructions.
```bash theme={null}
curl --location 'https://oauth.sandbox.paxos.com/oauth2/token' \
--form grant_type=client_credentials \
--form client_id={client_id} \
--form client_secret={client_secret} \
--form scope='rewards:create_payout_groups rewards:write_monitoring_address rewards:read_rewards_details rewards:read_claims'
```
### Required Scopes
The following scopes are sufficient to complete the steps in this guide. Additional scopes exist for other Rewards Engine operations — each API reference page lists the scope required for that specific endpoint.
| Scope | Purpose |
| ---------------------------------- | ---------------------------------------------- |
| `rewards:create_payout_groups` | Create payout groups and their claim schedules |
| `rewards:write_monitoring_address` | Register reward addresses |
| `rewards:read_rewards_details` | View current rates and lifetime earnings |
| `rewards:read_claims` | List claim history |
> Scopes for each endpoint are listed in the **Authorizations** section in the [API Reference](/api-reference/endpoints/reward-addresses/overview).
## API Reference
| API Section | Description |
| ---------------------------------------------------------------------- | --------------------------------------- |
| [Payout Groups](/api-reference/endpoints/payout-groups/overview) | Create and manage payout groups |
| [Claims](/api-reference/endpoints/claims/overview) | Claim schedules and payout history |
| [Reward Addresses](/api-reference/endpoints/reward-addresses/overview) | Register and manage monitored addresses |
| [Reward Details](/api-reference/endpoints/reward-details/overview) | Current rates, earnings, and accruals |
| [Statements](/api-reference/endpoints/rewards-statements/overview) | Monthly reward statements |
## Get Started
Define where rewards are sent, at what rate, and on what schedule
Submit blockchain addresses for monitoring
Check rates, accruals, and available rewards
Track payout history and claim status
Access monthly reward statements
> Questions? Contact [Support](https://support.paxos.com).