# Airdrops

Source: https://docs.settlemint.com/docs/console/asset-lifecycle/airdrops
Open an airdrop add-on from the Asset lifecycle sidebar, read its airdrops and each airdrop's distribution, and find where every other add-on type opens.

"Push airdrop", "Vesting airdrop" and "Time-bound airdrop" each have their own entry under **Asset lifecycle** in the Console sidebar. The entry opens a table of that add-on's airdrops, and each airdrop opens a read-only detail screen with its distribution, cap, recipients and recovery date. The [Token distribution concept](https://docs.settlemint.com/docs/concepts/issuing-and-markets/token-distribution) explains how the three airdrop types differ.

An add-on is a contract that your DALP system deploys from an add-on factory to work with its tokens: an airdrop, an offering, an XvP settlement, a vote, a trading venue, an escrow or a custody gateway. Every add-on opens at a Console address built from its factory address, and the same address opens the other add-on types, each on its own screen or as one overview card. [Add-on types and where each opens](#add-on-types-and-where-each-opens) lists them. A change that an add-on approval rule holds is decided on the custody gateway's [Approvals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals) tab or in [Actions](https://docs.settlemint.com/docs/console/essentials/actions).

![The Push airdrop page with the Search airdrops field, Export and View, before any airdrop exists](https://docs.settlemint.com/docs/screenshots/console-addon-airdrops.light.en.webp)

[Screenshot] The "Push airdrop" page shows its table before any airdrop exists.

With no airdrop yet, the table reads "No data available yet", under a "Search airdrops…" field with "Export" and "View". Once airdrops exist, the columns are "Airdrop", "Distributed", "Recovery" and "Created".

## Before you start [#before-you-start]

- **A role that shows the entry.** The airdrop entries show to a System manager, an Asset manager, a Permission manager, an Owner, a Platform admin, and a holder of the Governance role on an asset. The "Custody gateway" entry shows to an Owner and a Platform admin.
- **A deployed add-on.** An airdrop type the system has no add-on for shows as a greyed entry. A System manager reads "Push airdrop is not deployed. Open Factories to deploy it." and the entry opens [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories). Anyone else reads "Push airdrop is not deployed. A system manager deploys it in Factories." [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories) lists every add-on factory with its type and address.

## Steps [#steps]

### Open the add-on [#open-the-add-on]

Open the add-on type's entry under **Asset lifecycle**. The page title is the type's name, and the breadcrumb reads "Asset lifecycle", then the type.

After the fixed entries, such as "Offerings" and "Venues", the sidebar shows one entry for each airdrop add-on the system has, then **Custody gateway**. When the system has two add-ons of one type, each entry carries the add-on's own name.

### Read the airdrops [#read-the-airdrops]

The table lists the add-on's airdrops:

- The **Airdrop** column carries the airdrop's name with the symbol of the token it distributes.
- **Distributed** shows the amount sent so far, out of the cap when the airdrop has one.
- **Recovery** reads "Scheduled" once the airdrop's owner has scheduled a withdrawal, and "None" otherwise.

The withdrawal can run from the "Recovery available" time on the detail screen, and it takes only the tokens no recipient can still claim. On a vesting airdrop, it leaves the unclaimed part of every allocation whose vesting has started, and those recipients keep claiming. On a push airdrop, whose recipients do not claim, it takes the whole balance.

Search with **Search airdrops…**. Each row's menu offers "View details" and "Copy address".

### Open an airdrop [#open-an-airdrop]

Select an airdrop row, or **View details** in its menu, to open the airdrop's detail screen. The header carries the airdrop's name and the date it was created, and reads "Scheduled" when a withdrawal is scheduled. A "Distribution" card lists the fields in [Airdrop details](#airdrop-details).

The Console has no control that creates an airdrop or schedules its recovery. A holder of the **Governance** role on the token creates an airdrop by calling its factory contract's `create` directly, and the airdrop's owner schedules a recovery on the airdrop contract.

## Read the other add-on types [#read-the-other-add-on-types]

The add-on address opens a different screen for each other type:

- An XvP settlement add-on shows the settlements table and **Create XvP settlement**. [XvP settlement](https://docs.settlemint.com/docs/console/my-assets/settlements) describes it, and its detail screen.
- An offering add-on shows the offerings table. An offering address takes you to the offering's operating screen when you operate the sale, and to its subscription view when you do not. [Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings) describes the operating screen.
- A votes add-on redirects to **Votes** under "Wealth".
- Any other add-on shows one **Add-on overview** card with the add-on's "Address", "Type" and "Category".

A vesting distribution created before withdrawal reserves were introduced keeps its whole balance reserved after its factory moves to the new implementation. Recipients can still claim, but owner recovery sends zero, even after all claims finish: the contract cannot reconstruct the older allocations from its records.

## Airdrop details [#airdrop-details]

The **Distribution** card on an airdrop's detail screen lists:

| Field | What it shows |
| --- | --- |
| Token | The token the airdrop distributes, or **Unknown token**. |
| Distributed | The amount sent so far. |
| Cap | The most the airdrop distributes, or **No cap**. The owner of a push airdrop can change it. |
| Recipients | How many wallets received tokens. |
| Recovery available | The earliest moment the scheduled withdrawal can run: seven days after scheduling or, when later, the end of a time-bound airdrop's claim window or a vesting airdrop's **Vesting must start by** deadline. It shows while a withdrawal is scheduled. |
| Vesting strategy | The vesting contract, on a vesting airdrop. |
| Vesting must start by | The deadline for a recipient to start vesting, on a vesting airdrop. |
| Merkle root | A fingerprint of the list of eligible wallets and amounts. The contract checks each claim, or each distribution the owner of a push airdrop sends, against it. |
| Address | The airdrop contract's address. |

## Add-on types and where each opens [#add-on-types-and-where-each-opens]

The Console groups add-on types by category. Each name in the table is the label the Console shows.

| Category | Add-on types | Where it opens |
| --- | --- | --- |
| Distribution | Push airdrop, Vesting airdrop, Time-bound airdrop | Its own entry under **Asset lifecycle** in the sidebar, with a list of its airdrops and a detail screen for each. |
| Distribution | Offerings | **Offerings** under **Asset lifecycle**. See [Offerings](https://docs.settlemint.com/docs/console/asset-lifecycle/primary-offerings). |
| Exchange | Settlements | **Settlements** under **Wealth**. See [XvP settlement](https://docs.settlemint.com/docs/console/my-assets/settlements). |
| Exchange | Trading venue | **Venues** under **Asset lifecycle**. See [Venue operations](https://docs.settlemint.com/docs/console/asset-lifecycle/venues). |
| Governance | Votes | **Votes** under **Wealth**. An add-on address of this type redirects there. See [Governance votes](https://docs.settlemint.com/docs/console/my-assets/votes). |
| Custody | Custody gateway | **Custody gateway** under **Asset lifecycle**. See [Approvals](https://docs.settlemint.com/docs/console/asset-lifecycle/custody-gateway-approvals). |
| Custody | Escrow | **Escrows** under **Asset lifecycle**. See [Escrows](https://docs.settlemint.com/docs/console/asset-lifecycle/escrows). |
| Custody | Sponsorship Paymaster | No sidebar entry. Its link opens an **Add-on overview** card. |
| Income | Yield | No sidebar entry. Its link opens an **Add-on overview** card. |
| Data | Price Resolver, Issuer-Signed Scalar Feed, Scalar Feed Adapter, Document Anchor Registry | No sidebar entry. Its link opens an **Add-on overview** card. |

The Console keeps the access manager and the governance timelock out of the sidebar. The access manager is an internal add-on that creates a dedicated access manager for an add-on such as a trading venue or the custody gateway. The factory list also holds token feature factories, such as Dividend yield or Permit, which add a feature you configure on the token, as [Token features](https://docs.settlemint.com/docs/concepts/modeling-assets/token-features) describes.

## You should see [#you-should-see]

- For an airdrop add-on, the airdrop you looked for is in the table, and its detail screen shows the same **Distributed** amount as the table row.
- After the owner schedules a recovery, the row reads "Scheduled" under "Recovery" and the detail screen shows **Recovery available**.

## Troubleshooting [#troubleshooting]

**An add-on entry is missing from the sidebar**

The airdrop entries show only to a System manager, an Asset manager, a Permission manager, an Owner, a Platform admin
and a holder of the Governance role on an asset. The **Custody gateway** entry shows only to an Owner and a Platform
admin. An airdrop type that the system never deployed shows greyed with the line "Push airdrop is not deployed", so
ask a System manager to deploy it in [Factories](https://docs.settlemint.com/docs/console/organisation-settings/factories).

**An address shows This page does not exist**

The address names an add-on or an instance the Console has no screen for. Add-ons other than airdrops, XvP settlements
and offerings have no instance screen, so an instance address of one of them shows "This page does not exist". Use the
add-on's own entry instead, or the **Add-on overview** card at the add-on address.

**A claim is refused during a corporate action**

An airdrop that holds a token for claimants is frozen for that token from the record date of a [corporate
action](https://docs.settlemint.com/docs/console/asset-management/manage/corporate-actions) that changes every holder's units by a ratio, such as
a stock split, until the action's step lands. Claims in that window are refused with a message that names the token
and the action. Claim again once the action has finished. After it, each claim pays its committed amount scaled by
every action since the root was set. An airdrop counts as one holder, so a claim rounds down to the action's unit and
is never lifted to one share.

## API routes [#api-routes]

| Task | Route |
| --- | --- |
| List add-on factories | `GET /api/v2/system/addon-factories` |
| Read one add-on factory | `GET /api/v2/system/addon-factories/{factoryAddress}` |
| List airdrops | `GET /api/v2/addons/airdrops` |
| Read one airdrop | `GET /api/v2/addons/airdrops/{airdropAddress}` |

The request and response fields of each route are in [the v2 API reference](https://docs.settlemint.com/docs/api-reference/v2).