The <Transaction /> components provide a high-level wrap around the entire transaction flow. It handles the transaction lifecycle, including gas estimation, fee sponsorship, and status updates.

Before using them, ensure you’ve completed all Getting Started steps.

​
Quick start

The Transaction component now supports a simplified shorthand version to streamline the integration process for developers. Instead of manually defining each subcomponent and prop, you can render Transaction without children, and it will automatically include our suggested implementation — complete with the TransactionButton and TransactionToast components.

If you’d like more customization, follow the implementation guide for our Transaction components below.

// @noErrors: 1109 - Cannot find name 'contracts'
import { Transaction } from "@coinbase/onchainkit/transaction"

const calls = [...];

<Transaction calls={calls} />

​
Props

TransactionReact

​
Walkthrough

1

Add calls

Execute one or multiple transactions using the Transaction component. You can pass transactions in either Call or ContractFunctionParameters format. The component will automatically apply batching logic if the user’s wallet supports it.

​
Types

// @noErrors: 2307
import { useCallback } from 'react';
import { Avatar, Name } from '@coinbase/onchainkit/identity';
import { 
  Transaction, 
  TransactionButton,
  TransactionSponsor,
  TransactionStatus,
  TransactionStatusAction,
  TransactionStatusLabel,
} from '@coinbase/onchainkit/transaction'; 
import type { LifecycleStatus } from '@coinbase/onchainkit/transaction';
import { Wallet, ConnectWallet } from '@coinbase/onchainkit/wallet';
import { useAccount } from 'wagmi';
import { calls } from '@/calls'; 

// ---cut-start---

const BASE_SEPOLIA_CHAIN_ID = 84532;
// ---cut-end---

export default function TransactionComponents() {
  const { address } = useAccount();

  const handleOnStatus = useCallback((status: LifecycleStatus) => {
    console.log('LifecycleStatus', status);
  }, []);

  return address ? (
    <Transaction
      chainId={BASE_SEPOLIA_CHAIN_ID}
      calls={calls}
      onStatus={handleOnStatus}
    >
      <TransactionButton />
      <TransactionSponsor />
      <TransactionStatus>
        <TransactionStatusLabel />
        <TransactionStatusAction />
      </TransactionStatus>
    </Transaction>
  ) : (
    <Wallet>
      <ConnectWallet>
        <Avatar className='h-6 w-6' />
        <Name />
      </ConnectWallet>
    </Wallet>
  );
};
2

Listen to LifecycleStatus

Take full control of your transactions data with the LifecycleStatus object via the onStatus prop. This TypeScript object provides statusName and statusData to keep you informed.

// @noErrors: 2307
import { useCallback } from 'react';
import {
  Transaction,
  TransactionButton,
  TransactionSponsor,
  TransactionStatus,
  TransactionToast,
  TransactionToastIcon,
  TransactionToastLabel,
  TransactionToastAction,
} from '@coinbase/onchainkit/transaction';
import {contracts} from '@/contracts';
// ---cut-before---

import type { LifecycleStatus } from '@coinbase/onchainkit/transaction'; 

// omitted for brevity

const handleOnStatus = useCallback((status: LifecycleStatus) => {  
  console.log('Transaction status:', status); 
}, []); 

// omitted for brevity

// Usage in component
<Transaction
  contracts={contracts}
  onStatus={handleOnStatus}
>
  <TransactionButton />
  <TransactionSponsor />
  <TransactionToast>
    <TransactionToastIcon />
    <TransactionToastLabel />
    <TransactionToastAction />
  </TransactionToast>
</Transaction>

The Lifecycle Status features seven states for the transaction experience.

import type { TransactionError } from "@coinbase/onchainkit/transaction";
import type { Address, TransactionReceipt } from "viem";
// ---cut-before---
type LifecycleStatus =
  | {
      statusName: 'init';
      statusData: null;
    }
  | {
      statusName: 'error';
      statusData: TransactionError;
    }
  | {
      statusName: 'transactionIdle'; // initial status prior to the mutation function executing
      statusData: null;
    }
  | {
      statusName: 'buildingTransaction'; // resolving calls or contracts promise
      statusData: null;
    }
  | {
      statusName: 'transactionPending'; // if the mutation is currently executing
      statusData: null;
    }
  | {
      statusName: 'transactionLegacyExecuted';
      statusData: {
        transactionHashList: string[];
      };
    }
  | {
      statusName: 'success'; // if the last mutation attempt was successful
      statusData: {
        transactionReceipts: TransactionReceipt[];
      };
    };
3

Sponsor with Paymaster capabilities

To sponsor your transactions with Paymaster capabilities, configure your OnchainKitProvider with the appropriate config.paymaster URL, then pass isSponsored={true} to the Transaction component.

Obtain a Paymaster and Bundler endpoint from the Coinbase Developer Platform.

// @noErrors:  2304 17008 1005
<OnchainKitProvider
  config={{ 
    paymaster: process.env.PAYMASTER_ENDPOINT, 
  }}
>

Next, pass isSponsored={true} to the Transaction component.

// @noErrors: 2580 2304 2322 - Cannot find name 'process', Cannot find name 'contracts'
import { Transaction, TransactionButton, TransactionSponsor } from "@coinbase/onchainkit/transaction"
// ---cut-before---
// omitted for brevity
<Transaction
  isSponsored={true}
  contracts={contracts}
>
  <TransactionButton />
  <TransactionSponsor />
</Transaction>

​
Using calls with Promises

Calls also accepts asynchronous functions that are resolved on each button click. This can be useful if you’re calling an API to retrieve transaction data.

These functions must resolve to Call[] or ContractFunctionParameters[].

In the example the calls data will be fetched from api.transaction.com when the user clicks the Transaction Button.

// @noErrors: 2322
import { Transaction, TransactionButton, LifecycleStatus} from '@coinbase/onchainkit/transaction';
import { baseSepolia } from 'wagmi/chains';

// ---cut-before---

const callsCallback = async () => { 
  const res = await fetch('api.transaction.com/createTransaction'); 
  const callData = await res.json(); 
  return callData; 
} 

export default function TransactionWithCalls() {

  return (
    <Transaction
      chainId={baseSepolia.id}
      calls={callsCallback}
      onStatus={(status: LifecycleStatus) => console.log('Transaction status:', status)}
    >
      <TransactionButton />
    </Transaction>
  );
}

​
Components

The components are designed to work together hierarchically. For each component, ensure the following:

  • <Transaction /> - Serves as the main container for all transaction-related components.
  • <TransactionButton /> - Handles the transaction initiation process.
  • <TransactionSponsor /> - Displays information about the sponsorship of transaction gas fees.
  • <TransactionStatus /> - Contains transaction status information and actions.
  • <TransactionStatusLabel /> - Displays the current status of the transaction.
  • <TransactionStatusAction /> - Provides additional actions based on the transaction status.
  • <TransactionToast /> - Displays a toast notification for the transaction status.
  • <TransactionToastIcon /> - Displays an icon in the transaction toast notification.
  • <TransactionToastLabel /> - Displays the label text in the transaction toast notification.
  • <TransactionToastAction /> - Provides additional actions within the transaction toast notification.

​
Component types