Clique Allocations API Endpoint

This page documents the /allocations endpoint of Clique’s ACS v4 API. It focuses on the exact HTTP method, headers, request body and response format.

Summary

URL: https://acs-v4.clique.tech/allocations
Method: POST
Protocol: HTTPS
Request body: JSON
Response body: JSON

HTTP Request

Method and URL


POST https://acs-v4.clique.tech/allocations

Headers

Minimal headers for backend usage:


accept: application/json, text/plain, */*
content-type: application/json

Generic browser-style headers, with placeholders:


accept: application/json, text/plain, */*
content-type: application/json
origin: <origin>
referer: <referer>
user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36

Replace <origin> with the claim site’s origin, for example https://tokenclaims.example.com.
Replace <referer> with the corresponding referer URL, often the same origin.

Request Body

The core request body has three required fields:


{
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "appId": "<app-id>",
  "deployment": "<deployment>"
}

Fields

Field	Type	Required	Description
`address`	string	Yes	Wallet address to check (typically an EVM address in `0x...` format).
`appId`	string	Yes	Application identifier registered with Clique (the APP_ID for the campaign).
`deployment`	string	Yes	Deployment or distributor name for that application.

Some campaigns may add extra fields. If you are integrating with an existing claim UI, mirror the exact body you see in the browser network inspector.

Response Body

The endpoint returns a JSON object with a top-level data array. Each entry in data represents one allocation record for the queried address.

Types (Conceptual)


type CliqueAllocationItem = {
  batch: string;
  addressHandler: string;
  allocation: string;
  claimAt: string; // ISO-8601 timestamp
  extra: {
    sig: string;      // cryptographic signature (opaque)
    proof: string[];  // Merkle proof (opaque)
    recipient: string;
  };
};
 
type CliqueAllocationResponse = {
  data: CliqueAllocationItem[];
};

Example: Eligible Wallet (Redacted)


{
  "data": [
    {
      "batch": "<batch>",
      "addressHandler": "<address>",
      "allocation": "12345",
      "claimAt": "2025-11-01T13:12:06.613415",
      "extra": {
        "sig": "0x<redacted-signature>",
        "proof": [
          "0x<redacted-proof-1>",
          "0x<redacted-proof-2>",
          "0x<redacted-proof-3>"
        ],
        "recipient": "<address>"
      }
    }
  ]
}

Example: Not Eligible

One common pattern for a not-eligible wallet is an empty data array:


{
  "data": []
}

The exact behaviour can differ between campaigns, but in general:

data.length > 0 and a non-zero allocation indicates an allocation exists.
data.length === 0 means there is no allocation for that address in this campaign.

Determining Eligibility

A simple and explicit rule you can apply in your integration:


function isEligible(response: CliqueAllocationResponse): boolean {
  return response.data.some((item) => Number(item.allocation) > 0);
}

This rule:

Treats any entry with a strictly positive allocation as eligible.
Works even if multiple records exist for a single address.

You can adjust this logic if a specific campaign documents different rules.

Example Requests

cURL


curl -X POST "https://acs-v4.clique.tech/allocations"       -H "accept: application/json, text/plain, */*"       -H "content-type: application/json"       -H "origin: <origin>"       -H "referer: <referer>"       -H "user-agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"       -d '{
    "address": "0x1234567890abcdef1234567890abcdef12345678",
    "appId": "<app-id>",
    "deployment": "<deployment>"
  }'

Python (`requests`)


import requests
 
API_URL = "https://acs-v4.clique.tech/allocations"
 
APP_ID = "<app-id>"
DEPLOYMENT = "<deployment>"
 
HEADERS = {
    "accept": "application/json, text/plain, */*",
    "content-type": "application/json",
    "origin": "<origin>",
    "referer": "<referer>",
    "user-agent": (
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) "
        "AppleWebKit/537.36 (KHTML, like Gecko) "
        "Chrome/122.0.0.0 Safari/537.36"
    ),
}
 
def check_wallet(address: str) -> dict:
    payload = {
        "address": address,
        "appId": APP_ID,
        "deployment": DEPLOYMENT,
    }
    response = requests.post(API_URL, json=payload, headers=HEADERS, timeout=15)
    response.raise_for_status()
    return response.json()

JavaScript / TypeScript (`fetch`)


const API_URL = "https://acs-v4.clique.tech/allocations";
const APP_ID = "<app-id>";
const DEPLOYMENT = "<deployment>";
 
export async function checkWallet(address: string) {
  const response = await fetch(API_URL, {
    method: "POST",
    headers: {
      accept: "application/json, text/plain, */*",
      "content-type": "application/json",
      origin: "<origin>",
      referer: "<referer>",
      "user-agent":
        "Mozilla/5.0 (Windows NT 10.0; Win64; x64) " +
        "AppleWebKit/537.36 (KHTML, like Gecko) " +
        "Chrome/122.0.0.0 Safari/537.36",
    },
    body: JSON.stringify({
      address,
      appId: APP_ID,
      deployment: DEPLOYMENT,
    }),
  });
 
  if (!response.ok) {
    throw new Error(`Clique API error: ${response.status} ${response.statusText}`);
  }
 
  return (await response.json()) as CliqueAllocationResponse;
}

Basic Error Handling

When you call the endpoint from your own code, implement at least:

A reasonable HTTP timeout.
Simple retry logic for transient network errors.
Logging of non-2xx responses for debugging.

For example, in Python:


import time
from typing import Optional
 
def safe_check_wallet(address: str, retries: int = 2, delay: float = 1.0) -> Optional[dict]:
    for attempt in range(1, retries + 1):
        try:
            return check_wallet(address)
        except requests.RequestException as exc:
            print(f"[Clique] Error for {address}: {exc} (attempt {attempt}/{retries})")
            time.sleep(delay)
    return None

Keep the error handling logic simple and predictable, and always validate the response structure before you rely on it in production code.