Batch Tranfers for Tokens

Batch-Transfer funcitonality is enabled automatically if you create the token from coinmaker at coin.defi.ao

Batch transfers are a feature in AO token contracts that let a process transfer tokens to multiple recipients in one message, instead of sending a separate message for each transfer. This is especially useful for large-scale distributions, like airdrops and rewards.

For developers you can run this script on your process (please review the batch transfer script before loading it):

https://raw.githubusercontent.com/Autonomous-Finance/coin-maker-mirror/refs/heads/master/packages/registry/scripts/patch-with-batch-transfer.lua

This script is intended as a general-purpose extension. If your token has custom logic, you may need to replicate your custom logic inside the batch transfer handler to preserve expected behavior.

Use the provided code as a starting point, and modify as necessary to ensure compatibility with your process.

There are multiple ways to run this on the process:

• aos into process, .editor , paste the code, .done

• aos into process, .load with a path to a local file that contains the code

• run local aoconnect script that sends an Eval message to the process, with the Data containing this code

This Batch-Transfer name and the CSV payload structure and the Cast tag are also planned to be included in the official token blueprint. Tokens that don't do batch transfers with this exact API will not work properly in the context of FLPs

Transfer with credit notices

{
  "process": "TOKEN_PROCESS",
  "data": "user1,amount1\nuser2,amount2",
  "tags": [
    {
      "name": "Action",
      "value": "Batch-Transfer"
    }
  ]
}

Transfer without credit notices

{
  "process": "TOKEN_PROCESS",
  "data": "user1,amount1\nuser2,amount2",
  "tags": [
    {
      "name": "Action",
      "value": "Batch-Transfer"
    },
    {
      "name": "Cast",
      "value": "Any value will do here, just for the Tag to be present"
    }
  ]
}

If you're handling large-scale distributions involving hundreds of transfers, we highly recommend using batch transfers without credit notices. Each credit notice generates a message that must be processed and paid for, and it also consumes process memory and compute resources. For large-scale distributions, we do not recommend including them.

Reading Batch-Transfers

The classic way to detect a transfer on AO is to monitor the DEBIT and CREDIT notices, which respectively acknowledge a token transfer.

However, since batch transfers can be configured to omit CREDIT notices, the correct way to acknowledge such transfers is to look for the BATCH-DEBIT-NOTICE. This will be followed by a corresponding transfer message that includes all recipient addresses and the total amounts.

Batch transfers are atomic—if there is a batch debit notice, it guarantees that all transfers in the batch have been executed.