Functionality

Architecture

The backend is written in Rust and can run locally or in self-hosted environments using warp, as well as on Vercel with its rust runtime.

You can integrate the backend functionality using our official endpoints (below), but we recommend self-hosting for improved reliability. This allows you to fork the repository and provide your own IPFS and Pinata access keys.

Feel free to reach out for guidance or feedback.

The official endpoints are documented in the Airdrops Indexers section.

Create: /api/create

Call this route to create a new Merkle airdrop campaign.

Prerequisites

Before creating a campaign, you'll need:

• The decimals of the token you're basing the campaign on
• A CSV file containing [address, amount] pairs for every campaign recipient

Download a template CSV file from the link below or preview it here.

Sablier Template for Airdrops (CSV)airstream-template.csv

tip

The CSV contains a header row, followed by address and amount pairs. Amounts should be in human-readable form—the API handles decimal padding automatically.

Description

Endpoint	/api/create
Method	POST
Query Params	{decimals: number}
Body	FormData on {data: File}
Response	See in Rust Overview TS (below)

type Response = {
  /** IPFS content identifier for the uploaded file */
  cid: string;
  /** Expected number of recipients */
  recipients: string;
  /** HEX root of the Merkle tree */
  root: string;
  /** Humanized status */
  status: string;
  /** Expected amount of assets required by the campaign */
  total: string;
};

Functionality

The /api/create route performs the following actions:

1. Validation and processing

• Validates the CSV file and its contents
• Adds decimal padding to every amount
• Builds the Merkle tree and generates a root hash
• Computes intermediary data (total expected amount, number of recipients)
• Prepares an object containing the list, tree, and computed data

2. Upload to IPFS

• Uploads the object as a JSON file to IPFS
• Retrieves the IPFS CID (unique identifier of the uploaded file)

3. Return data to client

• Returns the root hash, IPFS CID, and intermediary data to the client
• The client uses this data to call the factory and deploy a new campaign

Code

For implementation details, check out the source code:

create.rsGithub - sablier-labs/merkle-api

---

Eligibility: /api/eligibility

Call this route to check if a recipient is eligible to claim a stream from the Merkle airdrop campaign.

info

This endpoint uses authentication. Please reach out if you need to use our deployed endpoints in your application.

Prerequisites

To check eligibility for an address, you'll need:

• The recipient's address
• The CID of the IPFS file (see the create flow above) linked to the campaign

For obtaining the CID, see options in the Common flows page.

Description

Endpoint	/api/eligibility
Method	GET
Query Params	{address: string, cid: string}
Response	See in Rust Overview TS (below)

type Response = {
  /** Address of the requested recipient */
  address: IAddress;
  /** Amount the recipient is eligible for */
  amount: string;
  /** Position of the recipient in the list */
  index: 0;
  /** Merkle proof */
  proof: string[];
};

Functionality

The /api/eligibility route performs the following actions:

1. Retrieves the campaign's IPFS file and extracts the recipient list and Merkle tree
2. Searches for the provided wallet address

Code

For implementation details, check out the source code:

eligibility.rsGithub - sablier-labs/merkle-api

---

Validity: /api/validity

Call this route to check if an IPFS CID links to a valid Merkle airdrop campaign file. Since users may accidentally provide invalid IPFS CIDs, we use this route to perform sanity checks before allowing admins to create campaigns in the UI.

Prerequisites

To check validity, you'll need:

• The CID of the IPFS file linked to the campaign

For obtaining the CID, see options in the Common flows page.

Description

Endpoint	/api/validity
Method	GET
Query Params	{cid: string}
Response	See in Rust Overview TS (below)

type Response = {
  /** IPFS content identifier for the uploaded file */
  cid: string;
  /** Expected number of recipients */
  recipients: string;
  /** HEX root of the Merkle tree */
  root: string;
  /** Expected amount of assets required by the campaign */
  total: string;
};

Functionality

The /api/validity route performs the following actions:

1. Retrieves the campaign's IPFS file
2. Runs sanity checks on the file contents

Code

For implementation details, check out the source code:

validity.rsGithub - sablier-labs/merkle-api