Distributions
Create and manage token distributions. The Distributions API handles sending tokens to multiple recipients in batched transactions, with full status tracking and cancellation support.
Overview
A distribution is the core operation of Multisender — sending tokens from one wallet to many recipients in a single flow. The API splits large recipient lists into optimally-sized batches, submits them as individual on-chain transactions, and tracks the status of each batch. You can monitor progress with getStats(), inspect individual transaction hashes with getTransactions(), and cancel a distribution before it starts executing.
Recipients format
You can provide recipients as a CSV string ("address,amount\naddress,amount") or as a JSON array of [address, amount] tuples. Use whichever format is more convenient — both produce the same result.
Cancellation window
Distributions can only be cancelled in DRAFT or PREPARED status. Once a distribution enters EXECUTING status, it cannot be stopped — the on-chain transactions have already been submitted.
Key Concepts
Distribution
A token-sending operation targeting multiple recipients. Each distribution has a status lifecycle: DRAFT → PREPARED → EXECUTING → COMPLETED (or FAILED, CANCELLED). Contains chain/token info, total recipients, and total amount.
Transaction Batch
Multisender splits large distributions into multiple on-chain transactions. Each batch has its own status (PENDING → SUBMITTED → CONFIRMED or FAILED), transaction hash, and list of recipients it covers.
Distribution Status
DRAFT — created but not yet prepared. PREPARED — ready to execute. EXECUTING — transactions are being submitted on-chain. COMPLETED — all batches confirmed. FAILED — one or more batches failed. CANCELLED — manually cancelled before execution.
Idempotency Key
A unique string you provide to prevent duplicate distributions when retrying failed requests. If you send the same idempotencyKey twice, the second request returns the existing distribution instead of creating a new one.
Token Approval
ERC-20 tokens require an on-chain approve() transaction before distributing. You must approve the Multisender contract to spend your tokens via your wallet or web3 provider. Native tokens (ETH, MATIC, etc.) do not require approval.
Quick Start
distribute()
Create a new distribution — the primary action for sending tokens to multiple recipients
getStats()
Monitor distribution progress with aggregate transaction statistics
getTransactions()
Inspect individual transaction batches with on-chain hashes and statuses
cancel()
Cancel a distribution before it starts executing on-chain
Common Workflows
End-to-end distribution
Create a distribution, monitor its progress, and verify completion.
1
Approve token
Approve the Multisender contract to spend your ERC-20 tokens (skip for native tokens)
2
distribute()
Create the distribution with chain, token address, and recipients
3
getStats()
Poll for completion
4
getTransactions()
Get transaction hashes
Distribution with pre-built list
Create a recipient list first, then use it for distribution.
1
createDistributionList()
Create a list with recipients in one step
2
Approve token
Approve the Multisender contract to spend your ERC-20 tokens (skip for native tokens)
3
distribute()
Create the distribution using the list recipients
4
get()
Check the distribution status and details
5
getStats()
Monitor transaction progress
6
getTransactions()
Get transaction hashes for verification
Methods
sdk.distributions.distribute(request)
Create a new token distribution. Specify the target chain, token, and recipients as either a CSV string or an array of [address, amount] tuples. The distribution is created in DRAFT status and progresses through the status lifecycle automatically.
For large distributions, use CSV format — it is more compact and easier to generate from spreadsheets.
Token approval required
ERC-20 tokens require an on-chain approve() transaction before distributing. Approve the Multisender contract address to spend your tokens using your wallet or web3 provider. Native tokens (ETH, MATIC, etc.) do not need approval.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
request.chainId | number | Yes | Target blockchain chain ID (1=Ethereum, 10=Optimism, 8453=Base, 137=Polygon, 42161=Arbitrum) |
request.tokenAddress | string | Yes | Token contract address to distribute |
request.tokenSymbol | string | Yes | Token symbol (e.g. "USDC", "WETH") — must match the token at tokenAddress |
request.recipients | string[][] | No | Array of [address, amount] tuples — mutually exclusive with csv |
request.csv | string | No | CSV string with address,amount per line — mutually exclusive with recipients |
request.account | string | No | Sender wallet address (overrides the project default) |
request.idempotencyKey | string | No | Unique key to prevent duplicate distributions on retry |
Returns
Distribution
Created distribution with id, status (DRAFT), chainId, tokenSymbol, totalRecipients, totalAmount, and timestamps
Example
Notes
Provide either recipients or csv, not both
Use idempotencyKey to safely retry failed requests without creating duplicates
Chain IDs: 1=Ethereum, 10=Optimism, 8453=Base, 137=Polygon, 42161=Arbitrum, 11155111=Sepolia
ERC-20 tokens require a prior approve() to the Multisender contract — native tokens do not
See Also
getChains()
Find supported chain IDs and their names
get()
Check distribution status after creation
getStats()
Monitor distribution transaction progress
sdk.distributions.list(params?)
Retrieve all distributions with pagination support. Filter by name with search, sort by creation date, and paginate through results. Returns summary information for each distribution.
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 | Search distributions by name |
params.orderBy | string | No | Field to sort by |
params.orderDir | 'ASC' | 'DESC' | No | Sort direction ASC DESC |
Returns
PaginatedResponse<Distribution>
Paginated result with data array and meta (page, limit, total, totalPages)
Example
sdk.distributions.get(id)
Retrieve a distribution by ID. Returns full details including current status, chain and token info, recipient and amount totals, and timestamps. Use this to check the current state of a distribution.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The distribution ID |
Returns
Distribution
Distribution object with id, name, status, chainId, tokenAddress, tokenSymbol, totalRecipients, totalAmount, createdAt, and updatedAt
Example
Notes
Distribution statuses: DRAFT → PREPARED → EXECUTING → COMPLETED (or FAILED, CANCELLED)
See Also
list()
Browse all distributions to find an ID
getStats()
Get transaction completion statistics
getTransactions()
View individual transactions in this distribution
cancel()
Cancel this distribution if not yet executing
sdk.distributions.getStats(id)
Retrieve aggregate transaction statistics for a distribution. Shows the total recipients, total amount, and a breakdown of completed, pending, and failed transaction batches. Use this to monitor distribution progress.
Poll getStats() periodically to show a progress bar. When completedTransactions + failedTransactions equals the total, the distribution is done.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The distribution ID |
Returns
DistributionStats
Aggregate stats with totalRecipients, totalAmount, completedTransactions, pendingTransactions, and failedTransactions
Example
See Also
get()
Get full distribution details including status
getTransactions()
View individual transaction details and hashes
sdk.distributions.getTransactions(id, params?)
Retrieve individual transaction batches for a distribution with pagination. Each transaction represents a batch of recipients with its own on-chain status, transaction hash, and error message (if failed).
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The distribution ID |
params.page | number | No | Page number (default: 1) |
params.limit | number | No | Items per page (default: 10) |
Returns
PaginatedResponse<DistributionTransaction>
Paginated list of transaction batches with id, status, txHash, recipients array, and optional errorMessage
Example
Notes
Transaction statuses: PENDING → SUBMITTED → CONFIRMED (or FAILED)
Each transaction contains a recipients array with the addresses and amounts in that batch
Failed transactions include an errorMessage field explaining the failure
See Also
get()
Get the parent distribution details
getStats()
Get aggregate statistics instead of individual transactions
sdk.distributions.cancel(id)
Cancel a distribution that has not yet started executing. Only distributions in DRAFT or PREPARED status can be cancelled. Once execution begins and transactions are submitted on-chain, cancellation is no longer possible.
Cannot cancel distributions in EXECUTING, COMPLETED, or FAILED status. Check the status with get() before attempting cancellation.
Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The distribution ID to cancel |
Returns
Distribution
Updated distribution object with status set to CANCELLED
Example
See Also
get()
Check distribution status before cancelling
list()
Find the distribution ID to cancel
distribute()
Create a new distribution to replace the cancelled one
Menu
Search
Code
Generated Code