Skip to main content

Send batch transactions

You can send and manage batch transactions in MetaMask, using the methods specified by EIP-5792:

About atomic batch transactions​

An atomic batch transaction is a group of transactions that are executed together as a single unit. When a dapp requests to submit a batch of transactions atomically, MetaMask may prompt users to upgrade their externally owned account (EOA) to a MetaMask smart account. If the user accepts, MetaMask proceeds to upgrade the account and process the request as a single atomic transaction as specified by EIP-7702.

Smart accounts

MetaMask smart accounts are ERC-4337 smart contract accounts that support programmable account behavior and advanced features such as multi-signature approvals, transaction batching, and custom security policies.

See the Delegation Toolkit documentation for more information about smart accounts and their capabilities.

The key benefits of atomic batch transactions include:

  • Fewer clicks and less friction - Users only need to review and approve a single wallet confirmation, instead of multiple confirmations. For example, users can confirm a spending cap and swap in one step instead of two.
  • Faster completion times - Only a single atomic transaction is confirmed onchain, instead of multiple individual transactions.
  • Reduced gas fees - When multiple transactions are executed atomically, users only need to pay a single gas fee.

You can send batch transactions using third-party libraries or directly in your dapp.

Use third-party libraries​

You can send batch transactions using the following third-party libraries that support EIP-5792:

Send batch transactions​

1. Query whether atomic batch is supported​

Use wallet_getCapabilities to query whether MetaMask supports atomic batch transactions for a specific address and specific chain IDs. For example:

index.js
const capabilities = await provider // Or window.ethereum if you don't support EIP-6963.
  .request({
    "method": "wallet_getCapabilities",
    "params": [
      "0xd46e8dd67c5d32be8058bb8eb970870f07244567", // The user's wallet address.
      ["0x1", "0xaa36a7"] // (Optional) A list of chain IDs to query for.
    ],
  });

This method returns the status of the atomic capability for each chain ID. For example:

{
  "0x1": {
    "atomic": {
      "status": "ready"
    }
  },
  "0xaa36a7": {
    "atomic": {
      "status": "supported"
    }
  }
}

The atomic capability can have a status of supported or ready:

  • supported means MetaMask supports atomic batch transactions for the account and chain ID.
  • ready means MetaMask will prompt the user to upgrade their account to a MetaMask smart account. If the user approves, the status will upgrade to supported.

If the atomic capability is not supported or ready for a specified chain ID, MetaMask will not return anything for that chain ID. If you don't specify any chain IDs in wallet_getCapabilities, MetaMask will return all chains in the wallet where the atomic capability is supported or ready.

Supported networks

MetaMask currently supports atomic batch transactions on the following networks:

  • Ethereum Mainnet and Sepolia
  • Gnosis Mainnet and Chiado
  • BNB Smart Chain Mainnet and Testnet
  • OP Mainnet
  • Base Mainnet and Sepolia

MetaMask will support this feature on more networks as they adopt EIP-7702.

Atomic batch unsupported

2. Submit a batch of transactions​

Use wallet_sendCalls to submit a batch of transactions. For example:

index.js
const result = await provider. // Or window.ethereum if you don't support EIP-6963.
  request({
    "method": "wallet_sendCalls",
    "params": [
      {
        version: "2.0.0", // The version of the API format. This must be 2.0.0.
        from: "0xd46e8dd67c5d32be8058bb8eb970870f07244567", // The sender's address.
        chainId: "0xaa36a7", // The chain ID, which must match the currently selected network.
        atomicRequired: true, // Whether or not atomicity is required.
        calls: [ // The list of calls to send as a batch.
          {
            to: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
            value: "0x0"
          },
          {
            to: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
            value: "0x0"
          }
        ]
      }
    ],
  });
Atomic required parameter

MetaMask only supports using wallet_sendCalls to send atomic batch transactions (not sequential batch transactions), so atomicRequired can be set to either true or false. If the atomic capability is not supported, wallet_sendCalls will return an error.

This method returns a batch ID that you can use to track the status of the batch. For example:

{
  "id": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
}

3. Track the status of the batch of transactions​

Use wallet_getCallsStatus to track the status of the submitted batch of transactions, using the batch ID returned by wallet_sendCalls. For example:

index.js
const status = await provider // Or window.ethereum if you don't support EIP-6963.
  .request({
    "method": "wallet_getCallsStatus",
    "params": [
      "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331" // Batch ID.
    ],
  });

This method returns status information about the batch of transactions, including:

  • The status code of the batch.
  • Whether the batch was executed atomically. Currently, this will always be true if the execution was successful.
  • A list of transaction receipts.

For example:

{
  "version": "2.0.0",
  "chainId": "0xaa36a7",
  "id": "0xe670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331",
  "status": 200, // Status code. 200 means confirmed.
  "atomic": true, // Whether the calls were executed atomically.
  "receipts": [ // List of transaction receipts.
    {
      "logs": [
        {
          "address": "0xa922b54716264130634d6ff183747a8ead91a40b",
          "topics": [
            "0x5a2a90727cc9d000dd060b1132a5c977c9702bb3a52afe360c9c22f0e9451a68"
          ],
          "data": "0xabcd"
        }
      ],
      "status": "0x1",
      "blockHash": "0xf19bbafd9fd0124ec110b848e8de4ab4f62bf60c189524e54213285e7f540d4a",
      "blockNumber": "0xabcd",
      "gasUsed": "0xdef",
      "transactionHash": "0x9b7bb827c2e5e3c1a0a44dc53e573aa0b3af3bd1f9f5ed03071b100bb039eaff"
    }
  ]
}
note

If the calls were executed atomically in a single transaction, a single receipt is returned.

In some cases, calls can be executed atomically but in multiple transactions (for example, using eth_bundle on an L2 network resistant to reorgs). In these cases, atomic is true but multiple receipts are returned.

Resources​

On this page