QuotaProtocol

Overview

QuotaProtocol extends the standard Protocol by adding rate limiting and access control to message handlers.

It helps protect agents from spam, abusive callers, and excessive traffic by controlling how frequently other agents can invoke a handler. Limits can be configured globally or on a per-handler basis, while access control lists allow you to permit or deny requests from specific agent addresses.

Quota usage is tracked using the agent’s storage, ensuring request counts persist throughout the configured time window.

Create a QuotaProtocol

from uagents.protocol.quota import QuotaProtocol
 
quota = QuotaProtocol(
    storage_reference=agent.storage,
    name="quota",
    version=agent._version,
)
 
agent.include(quota)

Apply a Rate Limit

Use the rate_limit argument on on_message to limit requests.

from uagents.protocol.quota import RateLimit
 
@quota.on_message(
    ExampleMessage,
    rate_limit=RateLimit(
        window_size_minutes=1,
        max_requests=3,
    ),
)
async def handle(ctx, sender, msg):
    ...

This example allows each sending agent to make 3 requests per minute before further requests are rejected until the window resets.

Restrict Access

Use an AccessControlList to control which agents can access a handler.

from uagents.protocol.quota import AccessControlList
 
@quota.on_message(
    ExampleMessage,
    access_control_list=AccessControlList(
        default=False,
        allowed={"<agent_address>"},
    ),
)
async def handle(ctx, sender, msg):
    ...

Only the agents listed in allowed can access this handler.