Key-value stores

A key-value store is an off-chain list of address → value entries that a campaign reads on every reward computation. They back the dynamic eligibility lists described in Customization options — whitelists, blacklists, boosts and referrer maps — and changes propagate within roughly two hours, with no on-chain transaction.

This page is the technical reference: the endpoints you call and the bodies you send to create a store and manage its entries. For the product logic — what whitelists, blacklists and referral programs do, how precedence works, and how a store is wired to a campaign — see Customization options.

Historically, Merkl provisioned every store for you. Allowlisted integrators can now create and manage their own stores programmatically with their API key — the self-serve flow documented below.

Prerequisites

1. An API key. All self-serve requests authenticate with the X-API-Key header — see Auth & rate limits. The store you create is owned by your key's address; only that key can write to it.
2. A creator quota. Self-serve creation is allowlisted. The Merkl team grants your address a quota that bounds:
   • maxConfigs — how many stores you may own,
   • maxSizeLimit — the largest a single store may be (number of entries),
   • allowedTypes — which store types you may create (e.g. WHITELIST, BLACKLIST, BOOST, REFERRER).

Creating a store

POST /v4/key-value-stores/self

Headers:

X-API-Key: your-api-key
Content-Type: application/json

Body:

{
  "key": "my-whitelist",
  "type": "WHITELIST",
  "sizeLimit": 50000,
  "publicRead": true
}

You do not set the owner or access mode — the server forces the store's owner to your API key's address and its access mode to API_KEY (only your key can write entries).

The response returns the store's canonical key — your address joined to your suffix, e.g. 0xAbC…DeF_my-whitelist — along with the resolved type, accessMode (API_KEY), sizeLimit, publicRead and ownerAddress.

Managing your stores

{key} is the canonical key from the create response. PATCH accepts description, publicRead and sizeLimit (still bounded by your quota, and never below the store's current entry count). You can only manage stores you own.

Adding and removing entries

Once a store exists, manage its membership with the standard entry endpoints, authenticated with the same API key:

PUT /v4/key-value-stores/{key}/entries/batch — {key} is your canonical key; up to 1000 entries per request, upsert.

Headers:

X-API-Key: your-api-key
Content-Type: application/json

Body:

{
  "entries": [
    { "address": "0xA9DdD91249DFdd450E81E1c56Ab60E1A62651701", "value": "{\"isWhitelisted\":true}" }
  ]
}

Use DELETE /v4/key-value-stores/{key}/entries/{address} to remove a single entry. The value is a JSON string, and its shape must match the store type exactly — it is validated at write time, so a malformed body fails immediately with a 400:

Addresses are stored lowercased, so request casing doesn't matter. Writes are rejected once the store reaches its sizeLimit. Full endpoint details are in the API reference.

Reading entries

GET /v4/key-value-stores/{key}/entries lists a store's entries, paginated with page and pageSize (defaulting to 0 and 100). Pass value to filter by an exact value match.

curl "https://api.merkl.xyz/v4/key-value-stores/{key}/entries?page=0&pageSize=100"

Response:

{
  "entries": [
    {
      "address": "0xA9DdD91249DFdd450E81E1c56Ab60E1A62651701",
      "value": "{\"isWhitelisted\":true}",
      "createdAt": "2026-06-12T09:00:00.000Z",
      "updatedAt": "2026-06-12T09:00:00.000Z"
    }
  ],
  "total": 1,
  "page": 0,
  "pageSize": 100
}

Fetch a single entry with GET /v4/key-value-stores/{key}/entries/{address} (returns 404 if absent).

If the store was created with publicRead: true (the default), anyone can list its entries without authentication — convenient for a public referrer map, but avoid it for a whitelist backing a private LP deal. Otherwise reads require the owner's X-API-Key, the same key used to write entries.

Wiring a store to a campaign

Creating a store does not by itself affect any campaign. A campaign must reference the store's canonical key in its hook for the engine to apply it. See Customization options for how whitelists/blacklists are attached and how precedence works (a non-empty whitelist implicitly excludes every other address), and for the referral boost semantics.

Common errors