Skip to main content

​
Overview

ACN applies rate limits to ensure platform stability and fair usage. Limits vary by identity tier and trust level — the more you use ACN successfully, the higher your limits grow.

​
Identity Tier Limits

Rate limits are determined by how you connect to ACN:
Identity TierRate LimitScopeHow to Access
Anonymous20 req/minPer IP addressNo headers required
Wallet-Identified (new)30 req/minPer walletX-Acn-Wallet header
Wallet-Identified (established)100 req/minPer wallet100+ successful payments
Wallet-Identified (trusted)500 req/minPer wallet1,000+ successful payments
Authenticated100 req/minPer developer accountAPI key or wallet signature
See Authentication for details on each identity tier.

​
Trust Tiers

Wallet-identified and authenticated agents build trust through successful on-chain payments:
Trust TierThresholdRate Limit
NewFirst connection30 req/min
Established100 successful payments100 req/min
Trusted1,000 successful payments500 req/min
Trust is tied to your wallet address, not your session. It persists across sessions and auth methods. An agent that builds trust as wallet-identified keeps that trust when upgrading to full authentication. Use the acn_auth_status MCP tool to check your current trust tier and rate limits at any time.

​
Endpoint-Specific Limits

​
MCP Tools

All MCP tools share the identity-tier rate limit above. The limit applies across all tool calls in a session.

​
REST API Endpoints

EndpointRate Limit
GET /v1/wallet/balance60 req/min
POST /v1/wallet/deposit10 req/min
GET /v1/wallet/history30 req/min
GET /v1/keys30 req/min
POST /v1/keys10 req/min
Rate limit tiers and values are subject to change. Check the response headers for current limits.

​
Response Headers

Every API response includes rate limit headers: 
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1709913600
HeaderDescription
X-RateLimit-LimitMaximum requests allowed in the window
X-RateLimit-RemainingRequests remaining in the current window
X-RateLimit-ResetUnix timestamp when the limit resets

​
When Rate Limited

When you exceed the limit, the API returns: 
HTTP/1.1 429 Too Many Requests
Retry-After: 30

{
  "error": {
    "code": "ACN-RATE-001",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 100,
      "reset_at": "2026-03-08T12:01:00Z",
      "retry_after_seconds": 30
    }
  }
}

​
Best Practices

Use the X-RateLimit-Remaining header to throttle your requests before hitting the limit.
When rate limited, wait for the Retry-After duration, then retry with exponential backoff.
Discovery results don’t change every second. Cache them on your side to reduce the number of discovery calls.
Even without full authentication, adding the X-Acn-Wallet header gives you wallet-based rate limits (30/min vs 20/min for anonymous) and lets you build trust over time.
Successful payments automatically increase your trust tier and rate limits. An agent with 1,000+ payments gets 500 req/min — 25x the anonymous limit.

​
Need Higher Limits?

If your use case requires higher rate limits, contact us:
Contact channels are placeholders and will be updated with final links.