Bulk send

Bulk Send enables one-time batch crypto transfers to multiple recipient addresses. It is suitable for payroll payouts, rebate/reward distributions, partner settlements, and revenue sharing for e-commerce/advertising/content platforms. You only need to submit a request containing multiple bulk send items. Cobo will validate each item (address format checks and compliance verification such as KYA) and then decide whether to proceed with on-chain transfers based on the execution mode.

Prerequisites

Before you start, make sure you have completed the following:

Ensure the source_account has sufficient balance.
(Recommended) Configure a Webhook Endpoint to receive Bulk Send status updates and drive an automated retry workflow.

1. How to send in batch

1.1 Create a Bulk Send

To create a Bulk Send, provide:

source_account: Source account ID (e.g., M1001)
execution_mode: Execution mode (Strict / Partial)
payout_params: Array of bulk send items. Each item includes:
- token_id
- receiving_address
- amount
- description (recommended: include business-traceable info such as payroll slip No./user ID/batch ID)

curl -X POST "https://api.example.com/v1/payments/bulk_sends" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>" \
  -d '{
    "source_account": "M1001",
    "execution_mode": "Partial",
    "description": "january salary",
    "payout_params": [
      {
        "token_id": "ETH_USDT",
        "receiving_address": "0xabc123456789def0000000000000000000000000",
        "amount": "500.00",
        "description": "Salary 2026-01 | eid=10001"
      },
      {
        "token_id": "TRX_USDT",
        "receiving_address": "TQx8yq9hFJt2cNxxxxxxxxyyyyyyyyyy",
        "amount": "320.50",
        "description": "Salary 2026-01 | eid=10002"
      }
    ]
  }'

1.2 How to choose execution_mode

After receiving a Bulk Send request, Cobo first validates all addresses in the request (including format validation and compliance checks such as KYA). execution_mode determines what happens in two situations: when any item fails validation, and — for Strict batches only — when the on-chain transfer step completes only partially (a partially completed sweep). execution_mode does not guarantee that every item succeeds once validation passes, and it does not provide transaction-level atomicity beyond these two situations. Always check each item’s own status and validation_status instead of assuming a single outcome for the whole batch.

Behavior: Strict vs Partial

execution_mode	When a problem occurs	Batch and item outcome	What you need to do
`Strict`	Any item fails validation (for example, KYA rejected)	The batch status becomes `Failed` and every item is marked `NotExecuted`	Replace the problematic address(es) and resubmit the entire Bulk Send (must include all items)
`Strict`	The on-chain transfer step (sweep) completes only partially	The batch status becomes `Failed`	Inspect each item’s `status` individually before deciding whether and how to resubmit
`Partial`	One or more items fail validation	The validation failure is isolated: failed items are marked `NotExecuted` with `validation_status: ValidationFailed`; all validated items continue to on-chain transfer	Query failed items, replace addresses, and resend only the failed items

execution_mode governs only the failure paths described above. It does not guarantee that a Partial batch’s validated items will all succeed on-chain, or that a Strict batch is atomic beyond these paths. Always inspect each item’s status and validation_status individually, and check the batch status (PartiallyCompleted or Failed) before deciding whether to resend.

Recommended scenarios

Use Strict (strong consistency: all-or-nothing)
- Partner settlements (must take effect consistently within the same batch)
- Vendor payments (finance requires batch-level consistency)
- Any scenario where partial success is unacceptable
Use Partial (high throughput: partial failures allowed, retry later) — recommended whenever a single item’s validation failure must not block the rest of a valid batch:
- Global payroll payouts (large volume; a few bad addresses should not block the whole batch)
- Rebates/rewards airdrops (mixed address quality)
- Tips/revenue distribution for content platforms; merchant payout distribution for e-commerce/ads platforms (retry is acceptable)

Impact summary:

Strict improves financial consistency by failing the whole batch on any validation failure (marking every item NotExecuted) or a partially completed sweep (batch status Failed), but increases operational overhead: a validation failure forces a full resubmission, while a partially completed sweep requires you to inspect each item’s status individually before deciding what to resubmit.
Partial isolates validation failures to the affected items so the rest of the batch proceeds, which scales better and is more automation-friendly, but requires a retry workflow for the failed items.

1.3 Smart contract mechanism for Bulk Send

For Bulk Send on Ethereum, Cobo uses smart contracts to perform batch transfers. For other chains, Cobo uses regular transactions instead. In both cases, Cobo sends a callback message to your registered callback endpoint for each operation so that you can inspect the details and approve or deny execution. The exact mechanism may also vary based on your organization’s configuration — contact Cobo support for details. To learn how to set up and register a callback endpoint, see Introduction to Callbacks.

Approve operation (triggered when allowance is insufficient)

When the smart contract’s allowance for a token is insufficient, an approve call is first triggered on the token contract:

Function called: approve
calldata parameters:
- _spender: The batch transfer contract address (see table below)
- _value: The transfer amount

Transfer operation

After the approve completes, the actual transfer calls the sendToken function on the batch transfer contract:

Function called: sendToken
calldata parameters:
- token: The token contract address (see table below)
- recipients: List of recipient addresses
- values: Corresponding list of transfer amounts

Contract address reference

Since the contract addresses are fixed for each token, it is recommended to verify the contract addresses and function call information in your callback handler to ensure the callback completes correctly.

Chain	Token ID	Token contract address	Batch transfer contract address
Ethereum	ETH_USDT	`0xdac17f958d2ee523a2206206994597c13d831ec7`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
Ethereum	ETH_USDC	`0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
Arbitrum	ARBITRUM_USDT	`0xfd086bc7cd5c481dcc9c85ebe478a1c0b69fcbb9`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
Arbitrum	ARBITRUM_USDCOIN	`0xaf88d065e77c8cc2239327c5edb3a432268e5831`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
Base	BASE_USDT	`0xfde4c96c8593536e31f229ea8f37b2ada2699bb2`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
Base	BASE_USDC	`0x833589fcd6edb6e08f4c7c32d4f71b54bda02913`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
Polygon	MATIC_USDT	`0xc2132d05d31c914a87c6611c10748aeb04b58e8f`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
Polygon	MATIC_USDC2	`0x3c499c542cef5e3811e1192ce70d8cc03d5c3359`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
BNB Smart Chain	BSC_USDT	`0x55d398326f99059ff775485246999027b3197955`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
BNB Smart Chain	BSC_USDC	`0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d`	`0x3d963e23a9229d2acd25e9ffc358be1a35460ecc`
TRON	TRON_USDT	`TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t`	`TEmDa9FY9YBCg1HPL41RUnJorXRRV3rX7A`

2. Webhook-driven automation workflow (failure notification → query items → batch resend)

Cobo triggers a webhook event when the Bulk Send status transitions to any of the following:

Completed
PartiallyCompleted
Failed

Webhook payload example (Bulk Send Notification):

{
    "data_type": "PaymentBulkSend",
    "bulk_send_id": "8ecf2933-5ef2-4f1d-9b59-3f4ff017d16a",
    "request_id": "SendBatch-001",
    "source_account": "M1001",
    "execution_mode": "Partial",
    "status": "Completed",
    "created_timestamp": 1768875988,
    "updated_timestamp": 1768878524
}

Status can be one of:

Pending
Validating
Transferring
Completed
PartiallyCompleted
Failed

Recommendations

Trigger the resend workflow only when the status enters PartiallyCompleted or Failed. During Validating / Transfering, you may only display or monitor progress.
Implement webhook signature verification and idempotency handling (the same event may be replayed).

2.2 After a failure notification: query Bulk Send item details

After receiving a PartiallyCompleted or Failed webhook, call List bulk send items to query the status of each bulk send item:

Path parameter: bulk_send_id
Operation: list_bulk_send_items
Summary: List bulk send items

(Example pseudo endpoint)

curl -X GET "https://api.example.com/v1/payments/bulk_sends/{bulk_send_id}/items" \
  -H "Authorization: Bearer <YOUR_ACCESS_TOKEN>"

Each item includes two key status fields:

status (execution status of the item)
validation_status (address/compliance validation status)

Rules to focus on:

If status = Failed or NotExecuted → the item failed
If validation_status = ValidationFailed → the address did not pass Cobo KYA validation

For both cases, replacing the address is recommended.

2.3 Automated retry: replace addresses and resend in batch

Resend strategy depends on execution_mode:

A) Previous batch used Strict

Under Strict, if any item fails validation, the batch fails and every item is marked NotExecuted.
Under Strict, if the on-chain transfer step completes only partially, the batch status becomes Failed.
For the validation-failure path, resubmission must include all items. For a partially completed sweep, inspect each item’s status individually before deciding what to resubmit — do not assume every item needs resubmission.

Steps (validation-failure path):

Query items and identify those with validation_status: ValidationFailed.
Replace the addresses for those items (or fix other parameters causing failures).
Resubmit a new Bulk Send containing all items.

For a partially completed sweep, query each item’s status individually and use that to decide which items (if any) to resubmit — do not default to resubmitting the full batch.

`B) Previous batch used Partial`

Under Partial, successful items have already been transferred.
Therefore, on retry, submit only failed items (reduces the risk of duplicate transfers).

Steps:

Query items and filter failed items (status=Failed/NotExecuted or validation_status=ValidationFailed)
Replace the addresses for failed items
Create a new Bulk Send containing only these failed items

3. Reference implementation: webhook handling + auto resend (example)

This example demonstrates a typical workflow:

Receive webhook
If status is PartiallyCompleted / Failed, query items
Filter failed items and replace addresses (address replacement is handled by your business system)
Create a new Bulk Send for resend

Note: This is illustrative pseudo-code (Node.js style). Adjust based on your actual SDK and signature verification mechanism.

import express from "express";
import fetch from "node-fetch";

const app = express();
app.use(express.json());

function isTerminalFailedStatus(bulkStatus) {
    return bulkStatus === "Failed" || bulkStatus === "PartiallyCompleted";
}

function isItemFailed(item) {
    return item.status === "Failed" || item.status === "NotExecuted" || item.validation_status === "ValidationFailed";
}

async function replaceAddressForFailedItem(item) {
    const newAddress = await lookupNewAddressFromYourSystem(item);
    return { ...item, receiving_address: newAddress };
}

app.post("/webhooks/cobo", async (req, res) => {

    const event = req.body;
    const { bulk_send_id, status, source_account, execution_mode } = event;

    if (!isTerminalFailedStatus(status)) {
        return res.status(200).send("ok");
    }

    const itemsResp = await fetch(`https://api.example.com/v1/payments/bulk_sends/${bulk_send_id}/items`, {
        method: "GET",
        headers: { Authorization: `Bearer ${process.env.ACCESS_TOKEN}` }
    });
    const items = await itemsResp.json(); 

    const failedItems = items.filter(isItemFailed);

    const itemsToResend = [];
    if (isTerminalFailedStatus(status)) {
        for (const item of items) {
            if (item.status === 'Failed') {
                itemsToResend.push(item);  
            } else if (item.status === 'NotExecuted' && item.validation_status === 'ValidationFailed') {
                itemsToResend.push(await replaceAddressForFailedItem(item));  
            }
        }
    }

    const createResp = await fetch(`https://api.example.com/v1/payments/bulk_sends`, {
        method: "POST",
        headers: {
            "Content-Type": "application/json",
            Authorization: `Bearer ${process.env.ACCESS_TOKEN}`
        },
        body: JSON.stringify({
            source_account,
            execution_mode: "Partial", 
            payout_params: itemsToResend.map(i => ({
                token_id: i.token_id,
                receiving_address: i.receiving_address,
                amount: i.amount,
                description: i.description
            }))
        })
    });

    const created = await createResp.json();
    console.log("Resend bulk send created:", created);

    return res.status(200).send("ok");
});

app.listen(3000, () => console.log("Webhook listener on :3000"));

4. Best practices

Always include business-traceable identifiers in description (e.g., batch_id + user_id/employee_id + period) for auditing, reconciliation, diagnosing failures, and address replacement.
Use different resend strategies for Strict vs Partial:
- Strict: for a validation failure, retry must include all items; for a partially completed sweep, inspect each item’s status individually before deciding what to resubmit
- Partial: retry only failed items (avoid duplicate payouts)
Webhook idempotency: use bulk_send_id + status + updated_timestamp as an idempotency key to avoid duplicated resend triggers.
Failure classification:
- validation_status=ValidationFailed：prioritize replacing the address
- status=Failed/NotExecuted： also recommended to replace the address (per your rule), and retain the failure reason for risk control and user messaging

Overview

Initial Setup

Pay-In

Funds Management

Reference

Prerequisites

1. How to send in batch

1.1 Create a Bulk Send

1.2 How to choose execution_mode

Behavior: Strict vs Partial

Recommended scenarios

1.3 Smart contract mechanism for Bulk Send

Approve operation (triggered when allowance is insufficient)

Transfer operation

Contract address reference

2. Webhook-driven automation workflow (failure notification → query items → batch resend)

2.2 After a failure notification: query Bulk Send item details

2.3 Automated retry: replace addresses and resend in batch

A) Previous batch used Strict

`B) Previous batch used Partial`

3. Reference implementation: webhook handling + auto resend (example)

4. Best practices

​Prerequisites

​1. How to send in batch

​1.1 Create a Bulk Send

​1.2 How to choose execution_mode

​Behavior: Strict vs Partial

​Recommended scenarios

​1.3 Smart contract mechanism for Bulk Send

​Approve operation (triggered when allowance is insufficient)

​Transfer operation

​Contract address reference

​2. Webhook-driven automation workflow (failure notification → query items → batch resend)

​2.1 Subscribe to Bulk Send status update events

​2.2 After a failure notification: query Bulk Send item details

​2.3 Automated retry: replace addresses and resend in batch

​A) Previous batch used Strict

​B) Previous batch used Partial

​3. Reference implementation: webhook handling + auto resend (example)

​4. Best practices

Prerequisites

1. How to send in batch

1.1 Create a Bulk Send

1.2 How to choose execution_mode

Behavior: Strict vs Partial

Recommended scenarios

1.3 Smart contract mechanism for Bulk Send

Approve operation (triggered when allowance is insufficient)

Transfer operation

Contract address reference

2. Webhook-driven automation workflow (failure notification → query items → batch resend)

2.1 Subscribe to Bulk Send status update events

2.2 After a failure notification: query Bulk Send item details

2.3 Automated retry: replace addresses and resend in batch

A) Previous batch used Strict

`B) Previous batch used Partial`

3. Reference implementation: webhook handling + auto resend (example)

4. Best practices