Airdrop distribution reads

An airdrop distributes tokens to a set of recipients. DALP runs airdrops as a system add-on, so an operator deploys an airdrop add-on and the distributions created under it become readable through this surface. Use these endpoints to query the airdrop distributions deployed in your system. An integration or operator reads this state to show which distributions exist, which token each one pays out, and how many recipients have received an allocation. The surface is read only: it lists and reads deployed airdrop instances, and it does not create, claim, or distribute.

DALP exposes airdrops through the Platform API, the SDK, and the CLI. The API and SDK share the same read model. Every read is scoped to the active system and the chain the request targets, so a caller sees only the distributions deployed under their own system.

DALP supports three airdrop variants, and one read model covers all of them. Each row carries a typeId that names its variant:

Vesting fields are populated only for vesting-airdrop rows. Push and time-bound rows leave them empty.

Before you read

A read needs at least one airdrop add-on deployed in the active system. If the system has no airdrop add-on, both the list and the read reject the request with DALP-0683. To deploy one, see Install addons, then retry the read.

Do not use this page as a substitute for the API Reference. Use the API Reference for exact request and response fields, and the CLI Command Reference for command syntax.

List airdrop distributions

The list endpoint returns the airdrop distributions deployed in the active system, across all three variants, on the chain the request targets.

GET /api/v2/addons/airdrops

Each row reports its variant, name, distributed token, distribution cap, the amount already transferred, withdrawal scheduling, the vesting fields for vesting variants, and the creation timestamp. The distributed token resolves to its address, symbol, and decimals when that token is indexed in the caller's tenant. For a token the caller's tenant has yet to index, the token reference is empty and the response still carries the raw base-unit amounts.

Filter, sort, and paginate the collection:

• Filter by typeId to scope the list to one variant. This field is faceted, so the response also reports the available variant values for the current result set.
• Filter by token to match the distributed token address exactly.
• Filter by systemAddon to match the deploying factory address. The address must belong to an airdrop add-on registered for the active system, or the request fails with DALP-0685.
• Use global search to match across the airdrop address, name, and variant.
• Sort by createdAt. The list sorts by createdAt by default.

const page = await client.addons.airdrop.list({
  query: {
    limit: 25,
    offset: 0,
    sortBy: "createdAt",
    sortDirection: "desc",
    filters: [{ id: "typeId", operator: "eq", value: "vesting-airdrop" }],
  },
});

for (const airdrop of page.data) {
  console.log(airdrop.id, airdrop.typeId, airdrop.name, airdrop.token?.symbol);
}

console.log(page.meta.total);

Read one airdrop distribution

The read endpoint fetches a single airdrop distribution by address, scoped to the active system.

GET /api/v2/addons/airdrops/{airdropAddress}

The read response carries the same fields as a list row and adds recipientCount. This count reports the distinct accounts that have received an allocation from the distribution, taken from indexed recipient records. Use the count to show distribution reach without expanding the full recipient list.

const airdrop = await client.addons.airdrop.read({
  params: { airdropAddress: "0xAIRDROP" },
});

console.log(airdrop.data.typeId, airdrop.data.name, airdrop.data.recipientCount, airdrop.data.amountTransferredExact);

A read resolves only within the system that owns the airdrop. A request for an airdrop deployed under a different system fails with DALP-0685. A request for an address that the active chain has not yet indexed fails with DALP-0684.

CLI coverage

The DALP CLI exposes the same read surface under dalp airdrops, so an operator can list and inspect distributions from the terminal:

dalp airdrops list
dalp airdrops read 0xAIRDROP

Error codes

Airdrop reads return a stable DALP-NNNN identifier when a request cannot resolve. Map the code your integration receives to the fix below before retrying. For the full catalog with HTTP status and retryability per code, see the Platform API error reference.

DALP-0684 clears on its own once indexing catches up after a recent deployment, so a short retry is safe. DALP-0683 and DALP-0685 flag a request that needs a change first. Deploy an add-on, or target one that belongs to the active system, then retry.

Related references

• Install addons
• API integration getting started
• API Reference
• Platform API error reference
• CLI Command Reference