Lists

Create and manage recipient lists for token distributions. Lists store wallet addresses with optional amounts, labels, and tags. Add recipients individually, in bulk, or by importing CSV files. Use createDistributionList or importCsvDistribution for one-step list+recipients creation.

Overview

Recipient lists are the foundation of every distribution. A list is a reusable collection of wallet addresses with optional amounts, labels, and tags. You can build lists incrementally — adding recipients one by one or in bulk — or create them in a single step with createDistributionList(). For spreadsheet-based workflows, importFromCsv() and importCsvDistribution() accept CSV data directly. Once your list is ready, pass it to the Distributions API to execute the token send.

Reusable lists

Lists persist across distributions. Create a list once and use it for multiple distributions — no need to re-import recipients each time.

Choose the right import method

For small lists (< 50 recipients), use addRecipientsBulk() with JSON. For large lists from spreadsheets, use importFromCsv() or importCsvDistribution(). For one-off sends, createDistributionList() combines creation and population.

Deletion is permanent

Deleting a list removes all its recipients permanently. There is no undo — make sure you no longer need the list before calling delete().

Key Concepts

Recipient List

A named collection of recipients. Each list has a unique ID, a display name, optional notes, and a recipientCount. Lists can be reused across multiple distributions.

List Item / Recipient

An individual entry in a list. Contains a wallet address, address type (EVM, SOLANA, TRON, etc.), optional amount, label, metadata, and tags. Each recipient has a unique recipientId within the list.

Address Type

The blockchain address format for a recipient: EVM (Ethereum, Polygon, Arbitrum, etc.), SOLANA, TRON, MOVE_EVM, or TON. Determines address validation rules. EVM addresses also support ENS name resolution.

CSV Import

Import recipients from comma-separated data. Use importFromCsv() for file uploads into existing lists, or importCsvDistribution() to create a new list from a CSV string in one step. Format: address,amount per line.

Distribution List

A list created with recipients included in a single API call via createDistributionList(). Ideal for one-off distributions where you already have all recipient data as JSON — no separate create + addRecipients steps needed.

Quick Start

create()

Create a new empty recipient list and populate it step by step

addRecipient()

Add a single recipient with address, amount, label, and tags

importFromCsv()

Import recipients into an existing list from a CSV file upload

createDistributionList()

Create a list with all recipients in one step — no separate add calls

Common Workflows

Build a list from scratch

Create a list, add recipients individually or in bulk, then verify the results.

1

create()

Create a new empty list with a name and optional notes

2

addRecipientsBulk()

Add multiple recipients in a single request for best performance

3

getRecipients()

Verify the imported recipients with pagination

4

Approve token

Approve the Multisender contract to spend your ERC-20 tokens (skip for native tokens)

5

distribute()

Use the list for a token distribution

Quick distribution list

Create a ready-to-distribute list in a single API call.

1

createDistributionList()

Create the list with recipients, chain, and token info in one step

2

Approve token

Approve the Multisender contract to spend your ERC-20 tokens (skip for native tokens)

3

distribute()

Execute the distribution using the newly created list

Methods

sdk.lists.list(params?)

Retrieve all recipient lists with pagination. Supports search by name, ordering, and page navigation.

Parameters

NameTypeRequiredDescription

params.page

number

No

Page number (default: 1)

params.limit

number

No

Items per page (default: 10)

params.search

string

No

Filter lists by name

params.orderBy

string

No

Field to sort by

params.orderDir

'ASC' | 'DESC'

No

Sort direction

ASC
DESC

Returns

PaginatedResponse<RecipientList>

Paginated result with data array and meta (page, limit, total, totalPages)

Example

See Also

create()

Create a new recipient list

get()

Get details for a specific list by ID

sdk.lists.create(request)

Create a new empty recipient list. After creation, populate it using addRecipient, addRecipientsBulk, or importFromCsv.

Parameters

NameTypeRequiredDescription

request.name

string

Yes

Display name for the list

request.notes

string

No

Optional description or notes about the list

Returns

RecipientList

Created list object with id, name, notes, recipientCount (0), and timestamps

Example

See Also

addRecipient()

Add recipients to the new list one by one

addRecipientsBulk()

Add multiple recipients at once

importFromCsv()

Import recipients from a CSV file

createDistributionList()

Create a list with recipients in one step instead

sdk.lists.get(listId)

Retrieve a recipient list by its ID. Returns list metadata including the current recipient count.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID

Returns

RecipientList

List object with id, name, notes, recipientCount, and timestamps

Example

See Also

list()

Browse all lists to find a list ID

getRecipients()

Get the actual recipients in this list

update()

Update this list name or notes

sdk.lists.update(listId, request)

Update a recipient list metadata. Pass any fields you want to change.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID to update

request

object

Yes

Fields to update (e.g. name, notes)

Returns

RecipientList

Updated list object

Example

See Also

get()

Get current list details before updating

delete()

Delete the list instead of updating

sdk.lists.delete(listId)

Permanently delete a recipient list and all its associated list items.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID to delete

Returns

void

No return value on success

Example

Notes

This action is irreversible — all list items will be removed

See Also

list()

Find the list ID to delete

create()

Create a replacement list

sdk.lists.getRecipients(listId, params?)

Retrieve recipients (list items) in a list with pagination. Each item includes the linked recipient address, amount, tags, and token info.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID

params.page

number

No

Page number (default: 1)

params.limit

number

No

Items per page (default: 10)

Returns

PaginatedResponse<ListItem>

Paginated list items with recipient details, amounts, tags, and token info

Example

See Also

addRecipient()

Add a new recipient to this list

removeRecipient()

Remove a recipient from this list

get()

Get the list metadata and total recipient count

sdk.lists.addRecipient(listId, request)

Add a single recipient to a list. Specify the wallet address, address type, and optional amount, label, metadata, and tags.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID to add the recipient to

request.address

string

Yes

Wallet address or ENS name (ENS resolved for EVM chains)

request.addressType

AddressType

Yes

Blockchain address format

EVM
SOLANA
TRON
MOVE_EVM
TON

request.amount

string

No

Token amount in human-readable units (e.g. "10.5"). Required for distribution lists.

request.label

string

No

Human-readable label for the recipient

request.metadata

Record<string, unknown>

No

Arbitrary metadata object

request.tags

string[]

No

Tags for categorizing recipients

Returns

Recipient

Created recipient object with id, address, addressType, label, metadata, tags, and timestamps

Example

Notes

EVM addresses support ENS names (e.g. "vitalik.eth") which are resolved automatically

See Also

addRecipientsBulk()

Add multiple recipients at once for better performance

getRecipients()

View all recipients after adding

removeRecipient()

Remove this recipient later if needed

sdk.lists.addRecipientsBulk(listId, request)

Add multiple recipients to a list in a single request. Returns counts of successfully added, skipped (duplicates), and errored entries.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID

request.items

AddRecipientDto[]

Yes

Array of recipient objects — same shape as addRecipient request (address, addressType, amount, label, metadata, tags)

Returns

{ added: number, skipped: number, errors: string[] }

Summary: number added, number skipped (duplicates), and error messages

Example

Notes

Duplicate addresses within the list are skipped and counted in the skipped field

See Also

addRecipient()

Add a single recipient with full control

importFromCsv()

Import from a CSV file instead of building the array

sdk.lists.removeRecipient(listId, recipientId)

Remove a recipient from a list by their recipient ID.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID

recipientId

string

Yes

The recipient ID to remove (obtain from getRecipients)

Returns

void

No return value on success

Example

See Also

getRecipients()

Find the recipient ID to remove

addRecipient()

Re-add the recipient if removed by mistake

sdk.lists.importFromCsv(listId, file)

Import recipients into an existing list from a CSV file. Uses multipart/form-data upload. Returns detailed import results including failed rows with reasons.

Parameters

NameTypeRequiredDescription

listId

string

Yes

The list ID to import into

file

File | Buffer

Yes

CSV file with address and amount columns

Returns

ImportListResponse

Import summary with added, skipped, totalItems, totalFailed, and failed row details

Example

Notes

CSV format: address,amount (one recipient per line)

Failed rows include reasons: invalid_chainId, invalid_address, metadata_too_long, invalid_metadata_json

First 100 failed rows are returned in the response

See Also

create()

Create the list before importing

addRecipientsBulk()

Add recipients programmatically instead of CSV

importCsvDistribution()

Create a new list from CSV in one step

sdk.lists.createDistributionList(request)

Create a new recipient list with recipients included in a single request. Ideal for one-off distributions where you already have the recipient data as JSON.

Parameters

NameTypeRequiredDescription

request.name

string

Yes

List name

request.notes

string

No

Optional notes

request.chainId

number

No

Target chain ID — when omitted, EVM address validation is used

request.tokenAddress

string

No

Token contract address (optional for native tokens)

request.tokenSymbol

string

No

Token symbol

request.recipients

DistributionRecipientDto[]

Yes

Array of { address, amount, label?, tags? } objects

Returns

RecipientList

Created list with imported recipients

Example

See Also

distribute()

Execute the distribution after creating the list

create()

Create an empty list and add recipients separately

importCsvDistribution()

Create a distribution list from CSV instead of JSON

sdk.lists.importCsvDistribution(request)

Create a new distribution list by importing CSV data as a string. Combines list creation and CSV import in one step — no file upload needed.

Parameters

NameTypeRequiredDescription

request.name

string

Yes

List name

request.chainId

number

Yes

Target chain ID (e.g. 1 for Ethereum, 137 for Polygon)

request.csvData

string

Yes

CSV string with address,amount rows

request.notes

string

No

Optional notes

request.tokenAddress

string

No

Token contract address (optional for native tokens)

request.tokenSymbol

string

No

Token symbol

request.delimiter

string

No

CSV delimiter character (default: ",")

request.skipRows

number

No

Number of rows to skip from the beginning

request.hasHeader

boolean

No

Whether the CSV has a header row to skip (default: false)

Returns

RecipientList

Created list with imported recipients

Example

Notes

CSV format: address,amount per line — no header by default

Set hasHeader: true if the first row contains column names

See Also

distribute()

Execute the distribution after creating the list

createDistributionList()

Create a distribution list from JSON data instead

importFromCsv()

Import a CSV file into an existing list instead

Previous

deleteApiKey()

Next

list()

Menu

Search

Code

Generated Code