Navigate...
Lists
Create and manage recipient lists for token distributions. Lists store wallet addresses with amounts, labels, and tags. Build lists incrementally or create them in a single call.
Overview
Recipient lists are the foundation of every distribution. A list is a reusable collection of wallet addresses with amounts, labels, and tags.Three ways to create lists: - Incremental: create() → addRecipient() / addRecipientsBulk() — build the list step by step - One-step JSON: createDistributionList() — create list + add recipients in a single call - One-step CSV: importCsvDistribution() — create list from a CSV stringFor file uploads into existing lists, use importFromCsv(). Once your list is ready, pass its ID to createDraft() in the Distributions API.
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 creation method
For JSON data use createDistributionList(). For CSV strings use importCsvDistribution(). For CSV file uploads into existing lists use importFromCsv(). For incremental building use addRecipient() / addRecipientsBulk().
Deletion is permanent
Deleting a list removes it and all its recipient entries permanently. There is no undo.
Key Concepts
Recipient List
A named collection of recipients. Each list has a unique ID, display name, optional notes, and a totalItems count. Lists are reusable — one list can be used for multiple distributions.
List Item
An entry linking a recipient to a list. Contains amount, tags, and a reference to the recipient object (which has address, addressType, label, metadata).
Address Type
Blockchain address format. Currently only EVM (Ethereum, Polygon, Arbitrum, etc.) is supported. SOLANA, TRON, MOVE_EVM, and TON are coming soon. EVM addresses also support ENS name resolution (e.g. vitalik.eth).
CSV import
importFromCsv() — upload a CSV file into an existing list. importCsvDistribution() — create a new list from a CSV string. Both support customizable delimiters, headers, and row skipping.
Quick Start
Common Workflows
Quick distribution list
Create a ready-to-distribute list in a single SDK call, then use it for distribution.
1
createDistributionList()
Create list with all recipients in one step
2
createDraft()
Create a distribution referencing this list by `listId`
3
distribute()
Or use single-step flow to distribute directly
Incremental list building
Build a list step by step — useful when recipients arrive over time.
1
list()
Browse existing lists or create a new empty one
2
addRecipientsBulk()
Add recipients in batches as they become available
3
getRecipients()
Review the list contents before distributing
Methods
sdk.lists.list(params?)
Retrieve all recipient lists for your project with pagination. Use this to browse available lists before creating a distribution, or to find a list by name.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
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 (e.g. createdAt) |
params.orderDir | 'ASC' | 'DESC' | No | Sort direction ASC DESC |
Returns
PaginatedResponse<RecipientList>
Paginated list of recipient list objects
Errors
The request is not authorized
You do not have permission to access this resource
See Also
get()
Get details for a specific list by ID
createDistributionList()
Create a new list with recipients
sdk.lists.get(listId)
Retrieve a recipient list by ID. Returns list metadata including totalItems — the current number of recipients. Use this to verify a list before passing it to createDraft().
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID |
Returns
RecipientList
List object with metadata and recipient count
Errors
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
See Also
getRecipients()
View the actual recipients in this list
update()
Update list name or notes
createDraft()
Use this list for a distribution
sdk.lists.update(listId, request)
Update a recipient list name or notes. Only include the fields you want to change. Set notes: null to clear existing notes.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID to update |
request.name | string | No | Updated list name |
request.notes | string | null | No | Updated notes — set to null to clear |
Returns
RecipientList
Updated list object
Errors
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
Notes
Only include fields you want to change — omitted fields remain unchanged
sdk.lists.delete(listId)
Permanently delete a recipient list and all its entries. This action is irreversible — all recipients in the list are removed.
Deleting a list removes all its recipient entries permanently. Existing distributions that reference this list are not affected — they keep their own copy of recipients.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID to delete |
Returns
MessageResponse
Confirmation message ({ message: string })
Errors
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
Notes
This action is irreversible — all list items are permanently removed
sdk.lists.getRecipients(listId, params?)
Retrieve recipients (list items) in a list with pagination. Each item includes the linked recipient with wallet address, address type, label, and the amount and tags assigned in this list.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID |
params.page | number | No | Page number (default: 1) |
params.limit | number | No | Items per page (default: 10) |
params.orderBy | string | No | Field to sort by |
params.orderDir | 'ASC' | 'DESC' | No | Sort direction ASC DESC |
Returns
PaginatedResponse<ListItem>
Paginated list items with nested recipient details
Errors
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
See Also
addRecipient()
Add a new recipient to this list
removeListItem()
Remove an item by ID
get()
Get the list metadata and total count
sdk.lists.addRecipient(listId, request)
Add a single recipient to a list. Returns both the created recipient and the list item entry. EVM addresses support ENS names (e.g. vitalik.eth) which are resolved automatically.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID to add the recipient to |
request.address | string | Yes | Wallet address or ENS name (ENS resolved for EVM) |
request.addressType | AddressType | Yes | Blockchain address format EVM SOLANA TRON MOVE_EVM TON |
request.amount | string | Yes | Token amount in human-readable units (e.g. "10.5"). Must be > 0. |
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 categorization |
Returns
AddRecipientResult
{ recipient, listItem } — the created recipient and its list entry
Errors
Validation error
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
Notes
EVM addresses support ENS names (e.g. "vitalik.eth") — resolved automatically
Amount is in human-readable token units (e.g. "10.5" USDC), not wei
See Also
addRecipientsBulk()
Add multiple recipients at once for better performance
getRecipients()
View all recipients after adding
removeListItem()
Remove this item later
sdk.lists.addRecipientsBulk(listId, request)
Add multiple recipients to a list in a single request. Returns the count of successfully added recipients and validation error messages for any failed rows. Duplicate addresses already in the list are silently ignored.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID |
request.items | AddRecipientDto[] | Yes | Array of recipients — each with address, addressType, amount, and optional label, metadata, tags |
Returns
AddRecipientsBulkResult
Import summary with added count and validation errors
Errors
Validation error
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
Notes
Duplicate addresses within the list are automatically skipped
Check errors array for validation failures (invalid addresses, missing amounts, etc.)
See Also
addRecipient()
Add a single recipient with full return details
importFromCsv()
Import from a CSV file instead of building the array
sdk.lists.importFromCsv(listId, file, options?)
Import recipients into an existing list from a CSV file upload. Uses multipart/form-data. Returns detailed results including added count, total list size after import, and failed rows with reasons. Duplicate addresses already in the list are silently ignored.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID to import into |
file | File | Blob | Yes | CSV file with address,amount columns |
options.filename | string | No | Override the filename sent in the multipart upload (useful when passing a Blob instead of a File) |
Returns
ImportListResponse
Detailed import results with success/failure breakdown
Errors
Invalid file
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
Notes
CSV format: address,amount per line
First 100 failed rows are included in the response
Failed row reasons: invalid_address, missing_amount, invalid_amount, etc.
See Also
importCsvDistribution()
Create a new list from CSV string instead of uploading into existing
addRecipientsBulk()
Add recipients programmatically as JSON
sdk.lists.removeListItem(listId, listItemId)
Remove an item from a list. Get the listItemId from getRecipients(). Returns void on success.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID |
listItemId | string | Yes | List item ID to remove (from getRecipients() response) |
Returns
MessageResponse
Confirmation message ({ message: string })
Errors
Invalid list id
The request is not authorized
You do not have permission to access this resource
List or item not found
See Also
getRecipients()
Find the list item ID to remove
bulkDeleteRecipients()
Delete multiple items at once
sdk.lists.bulkDeleteRecipients(listId, request)
Delete multiple list items from a list in a single request. Pass the list item IDs returned by getRecipients() — not recipient IDs. Returns the number of items actually deleted.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
listId | string | Yes | List ID |
request.ids | string[] | Yes | List item IDs to delete (from getRecipients() response) |
Returns
BulkDeleteRecipientsResult
Deletion summary
Errors
Validation error
Invalid list id
The request is not authorized
You do not have permission to access this resource
List not found
Notes
Pass list item IDs (listItem.id), not recipient IDs
See Also
removeListItem()
Remove a single item when bulk is overkill
getRecipients()
Find the list item IDs to delete
sdk.lists.createDistributionList(request)
Create a new recipient list with all recipients in a single call. Returns the list object along with import statistics (added count, errors). This is the fastest way to create a ready-to-use list for distribution.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
request.name | string | Yes | List name |
request.notes | string | No | Optional notes |
request.recipients | DistributionRecipientDto[] | Yes | Array of { address, amount, label?, tags? } — all recipients for the list |
Returns
DistributionListCreateResult
Created list with import statistics
Errors
Validation error
The request is not authorized
You do not have permission to access this resource
See Also
createDraft()
Create a distribution using this list
importCsvDistribution()
Create a list from CSV data instead of JSON
sdk.lists.importCsvDistribution(request)
Create a new recipient list from a CSV string. Combines list creation and CSV import in one step — no file upload needed. Supports customizable delimiters, header detection, and row skipping.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
request.name | string | Yes | List name |
request.csvData | string | Yes | CSV string with address,amount per line |
request.notes | string | No | Optional notes |
request.delimiter | string | No | Column delimiter (default: ",") |
request.skipRows | number | No | Number of rows to skip from the beginning |
request.hasHeader | boolean | No | Whether CSV has a header row to skip (default: false) |
Returns
DistributionListCreateResult
Created list with import statistics
Errors
Validation error
The request is not authorized
You do not have permission to access this resource
Notes
CSV format: address,amount per line (no header by default)
Set hasHeader: true if the first row contains column names
Use delimiter to change the column separator (e.g. ";" for European spreadsheets)
See Also
createDistributionList()
Create from JSON data instead of CSV
importFromCsv()
Upload a CSV file into an existing list instead
sdk.lists.validateDistributionRecipients(request)
Validate a recipient set without creating a list. Returns valid: true when every entry passes, along with any warnings (for example, duplicate addresses). Use this as a dry-run before createDistributionList() or distribute() to catch issues up front.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
request.recipients | ValidateDistributionRecipientDto[] | Yes | Array of { address?, amount? } — amount is in human-readable token units. Missing or malformed values are returned in aggregated row errors. |
Returns
ValidateDistributionRecipientsResult
Validation summary
Errors
Validation error
The request is not authorized
You do not have permission to access this resource
Notes
This endpoint does NOT save a list — use createDistributionList() after validation passes
Amount is in human-readable token units (e.g. "10.5" USDC), not wei
See Also
createDistributionList()
Create the list once validation passes
distribute()
Validate before triggering a single-step distribution
Generated Code