# Airdrop ERC20 Claimable

## Key Features

* **Self-Claim Mechanism**: Users can claim their tokens directly from the contract UI.
* **Merkle-Based Allowlist (Optional)**: Use a Merkle root to allow only specific addresses to claim.
* **Public Claim Support**: If no allowlist is defined, any wallet can claim tokens.
* **Claim Limits**: Limit how many tokens each wallet can claim.
* **Expiration Timestamp**: Define a time after which tokens can no longer be claimed.

## Deployment Parameters Explained

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2FzwGht9PFeSzcYiPyHG4o%2Fimage.png?alt=media&#x26;token=ae3a90ef-727d-4da7-98f3-406101b1378b" alt=""><figcaption></figcaption></figure>

Before deploying the contract, you must fill in the following fields:

| Field                      | Description                                                                                                                                                                                    |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**                   | A human-readable name for the contract (e.g., “Spring Token Drop”).                                                                                                                            |
| **Symbol**                 | A short, symbolic name (e.g., `SPRING`) for UI labeling.                                                                                                                                       |
| **Image**                  | Upload an image or logo for your airdrop. Appears in the UI interface.                                                                                                                         |
| **Token Owner**            | The address that owns the tokens and will approve the transfer of airdropped tokens. Must call `approve()` if not the deployer.                                                                |
| **Airdrop Token**          | Contract address of the ERC20 token to be distributed.                                                                                                                                         |
| **Airdrop Amount**         | Total number of tokens available for claim across all users.                                                                                                                                   |
| **Expiration Timestamp**   | UNIX timestamp (in seconds) after which tokens cannot be claimed. Use a converter (e.g., `https://www.unixtimestamp.com/`) to get the correct value.                                           |
| **Claim Limit per Wallet** | <p>Maximum number of tokens each wallet can claim.<br>- Use <code>0</code> to rely solely on the Merkle allowlist.<br>- Set any number to enforce a hard cap per wallet in public mode.</p>    |
| **Merkle Root**            | <p>(Optional) Merkle root generated from an allowlist.<br>- If none is needed, enter <code>0x</code> (zero address style).<br>- Used to validate claims off-chain and prove them on-chain.</p> |
| **Add Airdrop List**       | Optional tool to upload your allowlist and generate the Merkle root directly within the interface.                                                                                             |

Once all required fields are filled, click **Deploy Contract**.

### Using CSV for large address list

As with other contracts, the use of CSV lists is also permitted for a large number of wallets.

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2Fhghw9Cr9DLaszh8gamX1%2Fimage.png?alt=media&#x26;token=815eda32-70de-42b3-ac3f-d12fdacf576f" alt=""><figcaption></figcaption></figure>

## How Claims Work

After deployment:

* If a **Merkle root** is provided, users must **prove** they're on the allowlist by submitting a valid proof at claim time.
* If no Merkle root is set (`0x`), **any user** can claim up to the value set by `Claim Limit per Wallet`.
* All claims respect the **Expiration Timestamp**.

## Example Configuration (Testnet)

| Field                  | Example Value                         |
| ---------------------- | ------------------------------------- |
| Name                   | Airdrop ERC20 Claimable test contract |
| Symbol                 | CAERC20                               |
| Token Owner            | `0xAf16774D...BC0fB`                  |
| Airdrop Token          | `0xf3ba6c45...0bfa8edd`               |
| Airdrop Amount         | 10                                    |
| Expiration Timestamp   | `1715385600` (May 11, 2024)           |
| Claim Limit per Wallet | 1                                     |
| Merkle Root            | `0x` (no allowlist)                   |

### Notes

* If the token is **not owned by the contract**, the **token owner** must approve the contract to spend the total `Airdrop Amount`.
* You can reuse the `Add Airdrop List` option to **generate Merkle roots** with updated allowlists before deployment.
* Ideal for projects needing **public airdrops**, **whitelist campaigns**, or **time-limited incentives**.

## Embedding the Airdrop ERC20 Claimable Contract into Your DApp (DexAppBuilder)

After deploying and approving your token airdrop contract, you can make it available for users to interact with directly from your DApp. DexAppBuilder provides a visual way to embed a ready-made claim UI.

#### Step-by-Step: Add Claim Section to Your App

**1. Create a New Page**

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2FmrPoYJNhkn8UzodwEo5k%2Fimage.png?alt=media&#x26;token=5e7eeab5-91c2-4b72-983f-385f714c71d8" alt=""><figcaption></figcaption></figure>

* Go to **Admin > Manage Apps > Edit App**
* Under `Pages`, click **+ NEW PAGE**
* Enter a name (e.g., `Claim Tokens`) and click **CREATE**

**2. Add a Section**

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2FQ08DszmiPORRYrb6xEEq%2Fimage.png?alt=media&#x26;token=f870250d-cf85-48ec-bcdb-b9ddd23afea0" alt="" width="563"><figcaption></figcaption></figure>

* Inside the new page, click **+ ADD SECTION**

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2F50IGLOMFVEiGuCVWckUv%2Fimage.png?alt=media&#x26;token=c5e4b41c-2142-4d1f-a0cc-7729b9990923" alt="" width="375"><figcaption></figcaption></figure>

* In the modal, scroll or search for **DexGenerator Contract** (under Web3 category)
* Click to select it

**3. Select the Deployed Airdrop Contract**

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2FC9xar3jZFyLpuNNAy3DH%2Fimage.png?alt=media&#x26;token=86af4b5f-fadc-4c59-bba0-e6721dbe35a2" alt="" width="563"><figcaption></figcaption></figure>

* You'll now see a list of your deployed contracts
* Choose the one with the type **AIRDROPERC20CLAIMABLE**

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2Fmlehw2k3E9bpsxJDTpTi%2Fimage.png?alt=media&#x26;token=b2904fc2-dc20-42ef-aabb-282146a8b18e" alt=""><figcaption></figcaption></figure>

* Click it and preview the claim UI

**4. Save and Deploy**

* Click **SAVE** to add the section to your page

<figure><img src="https://1167648080-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FWrjgYUyO4ch1fBehrMEq%2Fuploads%2FvukQLqm9n0vOjaE2WHcs%2Fimage.png?alt=media&#x26;token=12a94856-176e-4b71-834f-ef6b9ffb5ce9" alt=""><figcaption></figcaption></figure>

* Back on the page layout, press **SAVE** again to publish the changes

## The User Experience: Claiming Tokens

Once published, users visiting this page will see:

* **Airdrop Token Info**: Address, symbol, and claim amount
* **Available Amount**: How much they can claim
* **Expiration Info**: Expiry date/time if set
* **CLAIM AIRDROP Button**: Executes the claim function

{% hint style="warning" %}
If the contract uses a Merkle tree (allowlist), the user must be included and provide a valid proof (handled automatically if integrated properly).
{% endhint %}

#### Optional Final Step: Publish Public Page

* Toggle the **VIEW PUBLIC PAGE** switch to make the contract page accessible to external users.
* This enables easy sharing of airdrop claim pages without embedding.