
Auth & rate limits
Authenticate Merkl API requests and understand request quotas
Anonymous requests work, on shared capacity and with a limit per IP address. For production, generate an API key and send it in the X-API-Key header. A key gives you attribution, support, and a quota of your own that does not depend on your IP address. The Merkl team can then move your key to a higher tier, with a larger quota and dedicated capacity.
Set MERKL_API_KEY to your API key.
curl -H "X-API-Key: ${MERKL_API_KEY}" https://api.merkl.xyz/v4/opportunities
The same key works for the Analytics API and for the endpoints that write data, such as key-value stores and campaign lists.
Rate limits
The limit that applies depends on the key you send. A new key starts on the free tier. The prefix of a key shows its tier: merkl_t2_... is a tier 2 key.
| Caller | Limit | Scope | Served by |
|---|---|---|---|
| No API key | 4,200 requests per minute, and 2,400 per minute on /v4/users/... | Per IP address | Shared pods |
Free key (merkl_t999_) | 10 requests per second | Per API key | Shared pods |
Tier 0 key (merkl_t0_) | 10 requests per second | Per API key | VIP pods |
Tier 1 key (merkl_t1_) | 50 requests per second | Per API key | VIP pods |
Tier 2 key (merkl_t2_) | 100 requests per second | Per API key | VIP pods |
Tier 3 key (merkl_t3_) | 200 requests per second | Per API key | VIP pods |
Tier 4 key (merkl_t4_) | 500 requests per second | Per API key | VIP pods |
Tier 5 key (merkl_t5_) | 1,000 requests per second | Per API key | VIP pods |
A request over the limit gets a 429 response. The limits without a key are burst ceilings on shared capacity, not a guaranteed throughput.
To move to a higher tier, contact the Merkl team. The tier is part of the key, so a tier change comes with a new key.
VIP pods
Requests with a tier 0 to tier 5 key are served by a dedicated pool of API pods. Anonymous and free-key traffic never reaches this pool, so a traffic spike from other callers does not slow your requests down. The pool also scales earlier and keeps more instances available at all times. For a production integration, this is the most stable way to call the Merkl API.
Limits on specific routes
| Route | Limit | Scope |
|---|---|---|
/v4/confidential-rewards/... | 30 requests per minute | Per IP address |
/v4/program-payload/airdrop/... | 60 requests per minute | Per IP address |
| Analytics API, with a free key | 2 requests per second | Per IP address |
The Analytics API applies the same tier 0 to tier 5 limits per key as the table above.
CDN limit on user routes
Every request goes through our CDN before it reaches the Merkl API. The CDN adds one limit of its own, on /v4/users/... routes: 12,000 requests per minute per source IP address (200 requests per second on average). It applies to every caller, whatever the API key.
- Going over the CDN limit blocks your IP address for 5 minutes. Pace your requests below it, especially for batch jobs.
- The CDN limit is per IP address. If all your backend traffic leaves through one NAT address, it all counts against that single address.
- Cached responses count toward the CDN limit, but not toward the API limits above. When the CDN already has a response in cache, it answers directly and the request never reaches the API.