Merkl Developer Portal logo

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.

CallerLimitScopeServed by
No API key4,200 requests per minute, and 2,400 per minute on /v4/users/...Per IP addressShared pods
Free key (merkl_t999_)10 requests per secondPer API keyShared pods
Tier 0 key (merkl_t0_)10 requests per secondPer API keyVIP pods
Tier 1 key (merkl_t1_)50 requests per secondPer API keyVIP pods
Tier 2 key (merkl_t2_)100 requests per secondPer API keyVIP pods
Tier 3 key (merkl_t3_)200 requests per secondPer API keyVIP pods
Tier 4 key (merkl_t4_)500 requests per secondPer API keyVIP pods
Tier 5 key (merkl_t5_)1,000 requests per secondPer API keyVIP 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

RouteLimitScope
/v4/confidential-rewards/...30 requests per minutePer IP address
/v4/program-payload/airdrop/...60 requests per minutePer IP address
Analytics API, with a free key2 requests per secondPer 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.