> 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/rewards.md).

# Rewards

The private messaging system includes a reward mechanism that distributes native COTI based on message activity.

## How rewards work

Rewards are tracked in 14-day epochs. Every encrypted cell generated by private messages contributes usage units to the sender's account for that epoch.

At the end of an epoch, the funded reward pool is distributed proportionally across participants.

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

## Core functions

The SDK exposes the following reward helpers:

* `getCurrentEpoch()`
* `getEpochForTimestamp()`
* `getContractConfig()`
* `getEpochUsage()`
* `getEpochSummary()`
* `getPendingRewards()`
* `claimRewards()`
* `fundEpoch()`

## Checking reward status

Use these calls when you want to inspect current or historical rewards:

```typescript
import {
  getCurrentEpoch,
  getEpochUsage,
  getEpochSummary,
  getPendingRewards
} from "@coti-io/coti-sdk-private-messaging";

const currentEpoch = await getCurrentEpoch(client);
const closedEpoch = currentEpoch - 1n;

const usage = await getEpochUsage(client, closedEpoch, wallet.address);
const summary = await getEpochSummary(client, closedEpoch);
const pending = await getPendingRewards(client, closedEpoch, wallet.address);
```

`getEpochUsage()` returns:

* `usageUnits`
* `totalUsageUnits`
* `pendingRewards`
* `hasClaimed`

`getEpochSummary()` returns:

* `totalUsageUnits`
* `rewardPool`
* `claimedAmount`
* `claimedUsageUnits`

## Claiming rewards

Rewards can only be claimed for closed epochs.

```typescript
import { claimRewards } from "@coti-io/coti-sdk-private-messaging";

const result = await claimRewards(client, {
  epoch: closedEpoch
});
```

The SDK performs preflight checks before broadcasting:

* the epoch must be earlier than the current epoch
* the configured wallet must not have already claimed that epoch
* the wallet must have rewards available to claim

The result includes:

* `transactionHash`
* `amount`

## Funding an epoch

Anyone can fund the reward pool for the current epoch or a future epoch:

```typescript
import { fundEpoch } from "@coti-io/coti-sdk-private-messaging";

const txHash = await fundEpoch(client, {
  epoch: currentEpoch,
  amountWei: 1000000000000000000n
});
```

`fundEpoch()` rejects:

* zero-value funding amounts
* past epochs

## Contract configuration

Use `getContractConfig()` when you need the contract-level timing and chunk limits:

* `epochDuration`
* `genesisTimestamp`
* `maxChunkCells`
* `maxChunksPerMessage`

This is useful when you want to inspect the deployed reward and chunking configuration without hardcoding assumptions.

## Important notes

* epochs are 14 days long
* rewards are pull-based, not automatic
* usage is based on encrypted cell count, not just logical message count
* the last claimant can receive the rounding remainder
* the full reward pool is distributed across claimants for the epoch


---

# 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/rewards.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.