How to create a mass payout via API

Overview

Mass payout API allows you to create multiple crypto payouts in one request from a merchant account to a list of recipient wallet addresses.

Use this guide to create a mass payout, track its processing status, handle partial completion, and receive webhook notifications until the mass payout reaches a final status.

Integration flow

1. Check account balance and ensure enough funds for payouts are available by using the method - [POST] account
2. Optionally pre-calculate payout commissions using Commission pre-calculation
3. Create the mass payout by using the method - [POST] payout/mass/create
   • After creating a mass payout request, Calypso sends PAYOUT_CHANGE_STATUS with state CREATION_IN_PROGRESS.
4. If payout verification is enabled, Calypso sends PAYOUT_CHANGE_STATUS (state: PENDING_CONFIRMATION)
   • Once the mass payout is confirmed, Calypso sends PAYOUT_CONFIRMED.
   • If the mass payout is declined, Calypso sends PAYOUT_CHANGE_STATUS with state CANCELED.
5. Once the mass payout is processed, Calypso sends PAYOUT_CHANGE_STATUS (state: IN_PROGRESS)
   • If the mass payout is not validated before transactions are created on the network, Calypso sends PAYOUT_VALIDATION_ERROR.
   • If the mass payout cannot be processed, Calypso sends PAYOUT_CHANGE_STATUS with state FAILED.
   • If one or more payouts from the list fail, Calypso sends PAYOUT_CHANGE_STATUS with state PARTIAL.
6. After a successful mass payout, Calypso sends PAYOUT_CHANGE_STATUS with state COMPLETED.
7. Get mass payout details and current status by using the method - [POST] payout/mass

Sequence

Names of requests on the scheme indicate certain payout API methods.

API methods

Create new mass payout - [POST] payout/mass/create

Request fields

Field	Type	Required	Description
account	string	Yes	Merchant account ID. The request will be sent for this account.
timestamp	number	Yes	Current Unix UTC timestamp in milliseconds. The value must not be less than 3 minutes in the past or greater than 3 minutes in the future.
payload	object	Yes	Object with mass payout creation data.

Payload fields

Field	Type	Required	Description
currency	string	Yes	Currency associated with the payout amount.
name	string	Yes	Mass payout name. Maximum length: 100 characters.
comment	string	No	Comment for the mass payout. Maximum length: 1000 characters. This value is displayed in the payouts table and reports when it is provided.
massAddresses	array	Yes	List of payout recipients and transaction details for each address.
executionDate	string	No	Execution date of the payout in date-time format. Can be used to schedule a payout for a specific date.
idempotencyKey	string	No	External ID in UUID format. Can be generated by the merchant while creating the payout to prevent duplicate requests.
externalId	string	No	Merchant-side external ID for the mass payout. Maximum length: 255 characters.

massAddresses fields

Field	Type	Required	Description
depositAddress	string	Yes	Recipient's crypto address.
amount	number	Yes	Transaction amount.
comment	string	No	Comment for the withdrawal transaction. Maximum length: 140 characters. This value is included in reports.

Request example

{
  "account": "text",
  "timestamp": 1,
  "payload": {
    "currency": "text",
    "name": "text",
    "comment": "text",
    "massAddresses": [
      {
        "depositAddress": "text",
        "amount": 1,
        "comment": "text"
      }
    ],
    "executionDate": "2025-11-17T09:55:55.567Z",
    "idempotencyKey": "123e4567-e89b-12d3-a456-426614174000",
    "externalId": "text"
  }
}

Response fields

Field	Type	Description
id	string	Calypso mass payout ID.
idempotencyKey	string	External ID in UUID format provided during payout creation.
companyId	string	ID of the company that created the mass payout.
account	string	Merchant account ID.
state	string	Current mass payout status.
comment	string	Comment for the mass payout, if provided.
name	string	Mass payout name.
currency	string	Currency associated with the payout amount.
totalWithdrawalAmount	number	Total amount of all transactions in the mass payout.
totalFee	number	Total service fee for the mass payout.
totalFeePercentage	number	Total service fee for the mass payout in percentage.
executionDate	string	Execution date of the payout, if provided.
errors	object	Validation errors grouped by withdrawal, if any errors occurred.
externalId	string	Merchant-side external ID for the mass payout, if provided.

Response example 200 OK

{
  "id": "string",
  "idempotencyKey": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "companyId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "account": "string",
  "state": "CREATION_IN_PROGRESS",
  "comment": "string",
  "name": "string",
  "currency": "string",
  "totalWithdrawalAmount": 0,
  "totalFee": 0,
  "totalFeePercentage": 0,
  "executionDate": "2025-12-16T10:52:46.659Z",
  "errors": {
    "withdrawalErrors": [
      {
        "withdrawalId": "string",
        "errors": [
          {
            "id": 0,
            "status": "SUCCESS",
            "errorResolved": true,
            "errorMessage": "string"
          }
        ]
      }
    ]
  },
  "externalId": "string"
}

Status lifecycle

Diagram nodes indicate mass payout statuses, arrows indicate processes a successful completion of which transfers a mass payout from one status to another.

Status	Description
CREATION_IN_PROGRESS	Mass payout creation has started.
PENDING_CONFIRMATION	A mass payout is awaiting confirmation from other process participants.
CONFIRMED	A mass payout has been confirmed by all required process participants and is ready for processing.
CANCELED	A mass payout has been canceled by merchant.
IN_PROGRESS	• Transactions for a mass payout have been created and are waiting to be sent to the network. • Transactions for a mass payout have been sent to the network and are awaiting confirmation from nodes.
FAILED	An error occurred when sending funds. There can be many reasons of the error. You may follow these remediation steps: 1. Wait a while and create a new similar payout. 2. Contact our technical support.
PARTIAL	One or more payouts from the list were not completed successfully. You can get a list of unsuccessful transactions in your personal Calypso account and resend unsuccessful mass payout transactions via UI.
COMPLETED	Funds are successfully credited to destination wallets.

Webhooks

Webhook event	Trigger	Merchant action
PAYOUT_CHANGE_STATUS	Mass payout status changed to CREATION_IN_PROGRESS, PENDING_CONFIRMATION, IN_PROGRESS, FAILED, PARTIAL, CANCELED, or COMPLETED.	Update mass payout status in your system.
PAYOUT_CONFIRMED	Mass payout was confirmed by all required process participants.	Continue tracking mass payout status.
PAYOUT_VALIDATION_ERROR	Mass payout validation failed before transactions were created on the network.	Check validation errors and create a new mass payout with corrected data, if needed.

After receiving a status change webhook, we recommend checking the reliability of the mass payout information via a request - [POST] payout/mass

Errors and edge cases

Case	Description
Not enough funds	Check the account balance before creating a mass payout.
Payout verification is enabled	The mass payout may wait for confirmation before processing starts.
Validation error	The mass payout was not validated before transactions were created on the network. Check the validation error details.
Processing failed	The mass payout was not completed. You can create a new mass payout with corrected data or contact technical support.
Partial completion	One or more payouts from the list failed while other payouts were completed. Check unsuccessful transactions and resend them if needed.

Related docs

Document	Link
Account API	[POST] account
Commission pre-calculation	Commission pre-calculation
Payout API reference	Payout API
Payout webhooks	Payout webhooks
Resend unsuccessful mass payouts via UI	How to resend unsuccessful mass payouts transaction via UI