atomic

Defined in EIP-5792

The atomic capability specifies how wallets execute batches of transactions, providing guarantees for atomic transaction execution. When supported, all transactions in a batch must succeed together or fail together.

Parameters

string

required

The atomic capability status for the current chain and account.Possible values:

"supported": Wallet will execute all calls atomically and contiguously
"ready": Wallet can upgrade to atomic execution pending user approval
"unsupported": No atomicity or contiguity guarantees

Returns

object

The atomic capability configuration for the specified chain.

Show Atomic capability properties

string

Indicates the level of atomic execution support available.

Example Usage

const capabilities = await provider.request({
  method: 'wallet_getCapabilities',
  params: ['0xd46e8dd67c5d32be8058bb8eb970870f07244567']
});

console.log(capabilities["0x2105"].atomic);

const result = await provider.request({
  method: "wallet_sendCalls",
  params: [{
    version: "1.0",
    chainId: "0x2105",
    from: "0xd46e8dd67c5d32be8058bb8eb970870f07244567",
    atomicRequired: true,
    calls: [
      {
        to: "0x1234567890123456789012345678901234567890",
        value: "0x0",
        data: "0xa9059cbb000000000000000000000000..."
      }
    ]
  }]
});

{
  "0x2105": {
    "atomic": {
      "supported": "supported"
    }
  }
}

{
  "0x2105": {
    "atomic": {
      "supported": "ready"
    }
  }
}

{
  "0x2105": {
    "atomic": {
      "supported": "unsupported"
    }
  }
}

Error Handling

Code	Message	Description
4100	Atomic execution not supported	Wallet does not support atomic transaction execution
5700	Atomic capability required	Transaction requires atomic execution but wallet doesn’t support it
5750	Atomic upgrade rejected	User rejected the upgrade to atomic execution capability

Use Cases

DeFi Operations

Atomic execution is crucial for DeFi operations where multiple steps must complete together:

// Swap tokens atomically
const swapCalls = await provider.request({
  method: "wallet_sendCalls",
  params: [{
    version: "1.0",
    chainId: "0x2105",
    from: userAddress,
    atomicRequired: true,
    calls: [
      // 1. Approve token spend
      {
        to: tokenAddress,
        value: "0x0",
        data: approveCallData
      },
      // 2. Execute swap
      {
        to: swapContractAddress,
        value: "0x0",
        data: swapCallData
      },
      // 3. Claim rewards (if applicable)
      {
        to: rewardsContractAddress,
        value: "0x0",
        data: claimCallData
      }
    ]
  }]
});

NFT Minting with Payment

// Mint NFT and pay fees atomically
const mintCalls = await provider.request({
  method: "wallet_sendCalls",
  params: [{
    version: "1.0",
    chainId: "0x2105",
    from: userAddress,
    atomicRequired: true,
    calls: [
      // 1. Pay minting fee
      {
        to: paymentAddress,
        value: "0x16345785d8a0000", // 0.1 ETH
        data: "0x"
      },
      // 2. Mint NFT
      {
        to: nftContractAddress,
        value: "0x0",
        data: mintCallData
      }
    ]
  }]
});

Error Handling

Handle atomic capability errors appropriately:

async function executeAtomicTransaction(calls) {
  try {
    // Check atomic capability first
    const capabilities = await provider.request({
      method: 'wallet_getCapabilities',
      params: [userAddress]
    });
    
    const atomicCapability = capabilities["0x2105"]?.atomic;
    
    if (!atomicCapability || atomicCapability === "unsupported") {
      throw new Error("Atomic execution not supported");
    }
    
    // Execute atomic transaction
    const result = await provider.request({
      method: "wallet_sendCalls",
      params: [{
        version: "1.0",
        chainId: "0x2105",
        from: userAddress,
        atomicRequired: true,
        calls
      }]
    });
    
    return result;
    
  } catch (error) {
    if (error.code === 4100) {
      console.error("Atomic execution not supported by wallet");
      // Fallback to sequential execution
      return executeSequentialTransaction(calls);
    } else {
      console.error("Atomic transaction failed:", error);
      throw error;
    }
  }
}

Relationship with EIP-7702

The atomic capability works with EIP-7702 to enable EOA (Externally Owned Accounts) to upgrade to smart accounts that support atomic transaction execution:

// Check if wallet can upgrade to atomic execution  
const capabilities = await provider.request({
  method: 'wallet_getCapabilities',
  params: [eoaAddress]
});

if (capabilities["0x2105"].atomic === "ready") {
  console.log("Wallet can upgrade to support atomic execution with user approval");
}

Best Practices

Check Capabilities First: Always verify atomic support before requiring it
Provide Fallbacks: Implement sequential execution as a fallback when atomic isn’t available
Use for Related Operations: Only require atomicity for operations that must succeed together
Clear Error Messages: Provide helpful error messages when atomic execution fails

The atomic capability is chain-specific. Always check support for the specific chain you’re targeting.

Apps should first check wallet capabilities using wallet_getCapabilities before sending requests requiring atomic execution.

Introduction

Quickstart

Guides

Framework Integrations

Reference

More

Basenames

Contribute

Parameters

Returns

Example Usage

Error Handling

Use Cases

DeFi Operations

NFT Minting with Payment

Error Handling

Relationship with EIP-7702

Best Practices

​Parameters

​Returns

​Example Usage

​Error Handling

​Use Cases

​DeFi Operations

​NFT Minting with Payment

​Error Handling

​Relationship with EIP-7702

​Best Practices

Parameters

Returns

Example Usage

Error Handling

Use Cases

DeFi Operations

NFT Minting with Payment

Error Handling

Relationship with EIP-7702

Best Practices