> For the complete documentation index, see [llms.txt](https://docs.coti.io/coti-documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coti.io/coti-documentation/private-messaging/skills/skill-1.md).

# COTI Rewards Management

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


---

# 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.coti.io/coti-documentation/private-messaging/skills/skill-1.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.