| name | coti-rewards-management |
| description | 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 funding rewards, inspecting epoch usage, or when the user mentions messaging rewards, 14-day epochs, or reward pool / usage units. |
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
- Call
get_current_epoch.
- Inspect closed epochs with
get_epoch_usage.
- Use
get_pending_rewards for a quick claimable amount.
- Use
get_epoch_summary for the full epoch totals.
Claiming rewards
- Find a closed epoch.
- Confirm rewards are pending.
- Call
claim_rewards.
Funding rewards
- Find the current epoch.
- 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
