Rate Limits

Claw402 implements rate limiting to ensure fair usage and maintain service quality for autonomous agent workloads.

Rate Limit Tiers

Plan	Transactions/Minute	Concurrent Sessions	Tool Calls/Minute
Developer	10	5	100
Production	100	50	1,000
Enterprise	Custom	Custom	Custom

Definitions:

• Transactions/Minute: Maximum blockchain transactions submitted per minute

• Concurrent Sessions: Maximum active payment sessions (x402.initialize_payment) at once

• Tool Calls/Minute: Total MCP tool invocations across all tools

Rate Limit Headers

Every MCP tool response includes rate limit information:

{
  "success": true,
  "result": { ... },
  "rate_limit": {
    "limit": 100,
    "remaining": 87,
    "reset_at": 1709315460
  }
}

Field	Description
limit	Maximum tool calls allowed in current window
remaining	Tool calls remaining in current window
reset_at	Unix timestamp when rate limit resets

Handling Rate Limits

Rate Limit Exceeded Response

When an agent exceeds rate limits, MCP tools return a standard error response:

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Transaction rate limit exceeded. Please retry after 30 seconds.",
    "retry_after": 30
  },
  "timestamp": 1709315400000
}

Best Practices for Agent Developers

1. Implement Exponential Backoff

import time
from claw402 import X402Provider

async def call_tool_with_backoff(tool_name, params, max_retries=3):
    for attempt in range(max_retries):
        result = await provider.call_tool(tool_name, params)

        if result.error and result.error.code == "RATE_LIMIT_EXCEEDED":
            retry_after = result.error.retry_after or (2 ** attempt)
            await asyncio.sleep(retry_after)
            continue

        return result

    raise Exception("Max retries exceeded")

2. Monitor Rate Limit Status

def check_rate_limit(result):
    if result.rate_limit.remaining < result.rate_limit.limit * 0.1:
        print(f"Warning: {result.rate_limit.remaining} tool calls remaining")

    # Implement agent throttling if approaching limit
    if result.rate_limit.remaining < 5:
        # Delay next operation
        time.sleep(2)

3. Batch Operations When Possible

Instead of multiple individual transactions, consolidate payment sessions:

# Bad: Multiple sessions for same recipient
for invoice in invoices:
    await provider.initialize_payment(invoice.amount, invoice.recipient)

# Good: Aggregate amounts per recipient
amounts_by_recipient = aggregate_invoices(invoices)
for recipient, total_amount in amounts_by_recipient.items():
    await provider.initialize_payment(total_amount, recipient)

4. Cache Balance Queries

Avoid redundant x402.query_balance calls:

from datetime import datetime, timedelta

class BalanceCache:
    def __init__(self, ttl_seconds=60):
        self.cache = {}
        self.ttl = timedelta(seconds=ttl_seconds)

    async def get_balance(self, wallet, provider):
        if wallet in self.cache:
            cached_balance, timestamp = self.cache[wallet]
            if datetime.now() - timestamp < self.ttl:
                return cached_balance

        balance = await provider.query_balance(wallet)
        self.cache[wallet] = (balance, datetime.now())
        return balance

5. Use Idempotency Keys

Prevent duplicate transactions from retry logic:

import uuid

# Generate unique idempotency key per payment intent
idempotency_key = str(uuid.uuid4())

result = await provider.initialize_payment(
    amount="0.1 SOL",
    recipient="[email protected]",
    idempotency_key=idempotency_key
)

# Safe to retry with same key - will not create duplicate session
if result.error:
    result = await provider.initialize_payment(
        amount="0.1 SOL",
        recipient="[email protected]",
        idempotency_key=idempotency_key  # Same key
    )

Tool-Specific Limits

Some MCP tools have additional rate constraints:

Transaction Submission Tools

• x402.authorize_transaction: Limited to 10 transactions/minute on Developer plan

• No additional limits on Production and Enterprise plans

Query Tools

• x402.query_balance, x402.verify_settlement, x402.estimate_fees: Follow standard tool call limits

• No tool-specific restrictions

WebSocket Rate Limits

WebSocket transaction streams have separate rate limits:

Plan	Concurrent Connections	Updates per Second
Developer	2	10
Production	10	100
Enterprise	Custom	Custom

Agent-Specific Considerations

Autonomous Agent Workflows

For long-running autonomous agents:

1. Implement circuit breakers to halt agent execution when rate limits are consistently exceeded

2. Use exponential backoff with jitter to avoid thundering herd on rate limit reset

3. Monitor rate limit metrics in agent telemetry dashboards

4. Configure approval policies to limit transaction volume

Multi-Agent Systems

For systems with multiple agents sharing a Claw402 account:

1. Distribute rate limit budget across agents using internal quotas

2. Implement agent-level rate limiting before calling Claw402 tools

3. Use separate Claw402 accounts for production vs. development agents

4. Monitor per-agent transaction volumes for anomaly detection

Upgrading Your Plan

If agents consistently hit rate limits:

1. Visit claw402.xyz/pricing

2. Compare plans based on agent transaction volume requirements

3. Upgrade instantly with no downtime

4. New rate limits take effect immediately

Monitoring Usage

Track agent transaction metrics in the Claw402 dashboard:

1. Log in to claw402.xyz

2. Navigate to "Agent Analytics"

3. View per-agent transaction volumes and rate limit utilization

4. Set up alerts for approaching limits

5. Analyze transaction patterns for optimization

Enterprise Plans

Need custom rate limits for high-volume agent workloads?

• Custom transaction throughput tailored to agent fleet size

• Dedicated MCP server infrastructure for guaranteed availability

• Priority support for production agent systems

• 99.99% uptime SLA with financial guarantees

Contact: [email protected]