Documentation
Ovryth docs
Product and technical documentation for Ovryth, an autonomous contribution-rewards agent that pays useful Telegram work in USDC on Base under a revocable onchain spending boundary.
Overview
Ovryth watches a linked Telegram group for useful community work, filters obvious farming, classifies qualifying messages against the room's rules, applies deterministic payout policy, and pays contributors in USDC on Base when all checks pass. The project keeps its budget in its own Base Account. Ovryth receives a bounded spend permission rather than unrestricted treasury custody.
How it works
The agent loop is: Telegram intake → deterministic prefilter → Groq classifier with Gemini fallback → deterministic policy → pay, hold, or refuse. Recipient selection happens outside the model and comes only from the wallet the Telegram user linked by DM. Before every real payout, Ovryth reads live permission state, fails closed if that state cannot be verified, simulates the transaction, and then submits OvrythPayer.pay() from the operator account.
Getting started
Earn in a room
Join a Telegram group where Ovryth is active. DM @Ovryth_bot with /wallet 0xYourAddress, then contribute substantive work in the group. A successful payout is replied to in-thread with the USDC amount, category, reason, and BaseScan link.
Open a room
Start at /open. You need a Base Account, USDC on Base, and a Telegram group where you are an admin. Connect your Base Account, choose a weekly allowance, complete Coinbase's hosted spend-permission consent, define your room rules, create the room, add @Ovryth_bot as a group admin, and send the one-time /link <code> command.
The current hosted permission consent is not documented as gasless. The owner account pays the permission-manager gas in this flow. The payout operator pays gas for normal automated payouts.
Core concepts
- The agent
- Ovryth runs inside a linked Telegram group. It filters obvious farming, classifies substantive work, applies deterministic payout policy, and can execute a USDC payment without a human signing each payout.
- Base Account
- The project owner smart account that holds the budget and authorizes the spend permission. Plain EOAs are not supported as room-owner budget accounts in the current implementation.
- Spend permission
- A revocable Base authorization naming OvrythPayer as spender and limiting how much USDC can be spent per period.
- Deterministic policy
- The model proposes a category and amount. Code then enforces confidence, owner-defined category ranges, member and room caps, remaining onchain allowance, and wallet state.
- Non-custodial payout
- Normal payout flow pulls the exact amount under the spend permission and forwards it to the linked contributor in the same transaction.
- Refusal
- A contribution that fails the prefilter, classifier, or deterministic policy. Public refusal replies are rate-limited while the refusal record stays stored.
- Hold
- Approved work with no linked payout wallet is held for 72 hours instead of paying an arbitrary address.
- Approximate account age
- Telegram does not expose exact account creation time. Ovryth uses an explicitly approximate signal from the numeric user id and tracks room tenure separately.
Room flow
The prefilter rejects messages under 24 characters or 3 words, link-only content, exact or near duplicates, members below configured floors, exhausted member/room caps, and rooms with no remaining spend allowance. Near-duplicate detection uses a 64-bit SimHash with Hamming distance up to 3, alongside an exact normalized SHA-256 content hash.
Messages that pass go to the structured classifier. Wallet addresses and explicit token or dollar amounts are masked before the model sees the text. The model can return only a category, proposed amount, reason, and confidence. It cannot return a recipient or arbitrary contract action.
Deterministic policy then checks confidence, the current rules version, account-age and tenure floors, member weekly budget, room daily budget, remaining onchain allowance, and wallet presence. Proposals above a category maximum are clamped down. Proposals below the owner-defined category minimum are normalized up to that minimum, then can still be reduced by tighter member, room, or onchain ceilings. If there is not enough headroom to pay at least the category minimum, the contribution is refused.
Telegram commands
/wallet 0x…- DM the bot to link your payout address.
/wallet 0x… confirm- Explicitly replace an already-linked wallet.
/rules- In a group, show that room's current rules. In DM, list your active rooms and public rule pages.
/start /help /commands- Explain how to link a wallet and earn in the current room.
/link <code>- Admin-only group binding. Ovryth also checks that the bot itself is an admin.
#question …- Admin-only classifier context for an open community question.
Console
The canonical showcase console is /console. Other rooms use /console/[slug]. The console exposes the budget, permission, current rules, payout/refusal ledger, sweeper state, and operator gas. Viewing a console is not treated as the authorization boundary. Mutating owner actions are authenticated.
Pause/resume and rules updates require a fresh canonical Base Account signature with a 10-minute TTL. Revocation is requested by the connected room-owner Base Account through the spend-permission SDK, then the backend confirms the revoke from chain state before marking the room revoked. The current revoke flow is account-paid.
Safety model
Ovryth treats Telegram messages and model output as untrusted. Message addresses and explicit amounts are masked before classification. The model never chooses the payout recipient. Recipient resolution happens from the contributor's stored DM-linked wallet after policy. Coinbase SpendPermissionManager remains the final spending boundary on Base, so an application-level mistake cannot raise the onchain allowance.
Money-moving code fails closed. If permission status cannot be read, the payout is not sent. A queued payout can be retried by the sweeper later. Transaction calls are simulated by default before broadcast.
API reference
Current app-level limits are 5 room creations/hour/IP, 60 paymaster requests/minute/IP, and 60 Telegram contributions/minute/chat. These counters use an in-memory limiter in the present demo deployment.
Technical details
Chain: Base mainnet, chain id 8453. USDC 0x8335…2913. Coinbase SpendPermissionManager 0xf852…67Ad. Verified OvrythPayer 0x4854…3999. The payer has no general withdraw, arbitrary-call, ETH receive, or rescue path. Normal payouts pull and forward the exact token amount in one transaction. The only other state-changing function is operator rotation.
Classifier order is Groq openai/gpt-oss-120b first, Gemini gemini-2.5-flash second. The repository currently verifies 51 Vitest tests and 7 Base-fork Foundry tests, for 58 automated tests total. See /proof for onchain evidence and the repository's docs/ARCHITECTURE.md for implementation-level detail.
Current limitations
Telegram account age is approximate. Deleted Telegram messages cannot be observed after deletion. Edits are flagged but confirmed transfers are not clawed back. The current generic rate limiter is in-memory and should be replaced with a durable distributed store for horizontal production scale. If both LLM providers fail, Ovryth stores the message but does not invent a payout or content-based refusal; automatic classifier retry is not implemented in the current webhook path.