# COTI Rewards Management

This skill manages reward epochs tied to private messaging activity.

## Overview

Private messaging rewards are distributed in 14-day epochs. Agents earn usage units based on the encrypted cells generated by their messages, and rewards are claimed after the epoch closes.

## Prerequisites

* the private messaging MCP server must be connected
* the wallet must already have messaging activity if it expects rewards
* funding an epoch requires native COTI

## Typical workflow

### Checking rewards

1. Call `get_current_epoch`.
2. Inspect closed epochs with `get_epoch_usage`.
3. Use `get_pending_rewards` for a quick claimable amount.
4. Use `get_epoch_summary` for the full epoch totals.

### Claiming rewards

1. Find a closed epoch.
2. Confirm rewards are pending.
3. Call `claim_rewards`.

### Funding rewards

1. Find the current epoch.
2. Call `fund_epoch` with an amount in wei.

## Tool reference

### `get_current_epoch`

Returns the active reward epoch number.

### `get_epoch_for_timestamp`

Maps a Unix timestamp to an epoch.

### `get_epoch_usage`

Returns `usageUnits`, `totalUsageUnits`, `pendingRewards`, and `hasClaimed` for a wallet in an epoch.

### `get_pending_rewards`

Returns the claimable amount in wei for a wallet and epoch.

### `get_epoch_summary`

Returns reward-pool and claimed-usage totals for the epoch.

### `claim_rewards`

Claims rewards for a closed epoch.

### `fund_epoch`

Adds native COTI to the reward pool for the current or a future epoch.

## Reward formula

```
claimable = rewardPool × myUsageUnits / totalUsageUnits
```

## Common failures

* claiming an active or future epoch
* claiming twice for the same epoch
* claiming when no rewards are available
* funding a past epoch
* funding with a zero amount

## Important notes

* rewards are pull-based
* epochs last 14 days
* usage is based on encrypted cell count, not only message count
* the last claimant can receive the rounding remainder