COTI Rewards Management

Guides COTI private-messaging reward epochs via MCP get_current_epoch, get_epoch_usage, get_pending_rewards, get_epoch_summary, claim_rewards, fund_epoch, and related tools. Use when claiming or fundi

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