Skip to content
Docs

<Transaction />

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 TransactionDefault component is a simplified version of the Transaction component, designed to streamline the integration process for developers. Instead of manually defining each subcomponent and prop, developers can use this shorthand version which renders our suggested implementation of the component and includes the TransactionButton and TransactionToast components.

If you'd like more customization, follow the implementation guide for our Swap component below.

import { TransactionDefault } from "@coinbase/onchainkit/transaction"
 
const calls = [...];
 
<TransactionDefault calls={calls} />

Props

TransactionDefaultReact

Walkthrough

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


TransactionComponents.tsx
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'; 
 
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>
  );
};

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.

import type { LifecycleStatus } from '@coinbase/onchainkit/transaction'; 
 
// omitted for brevity
 
const handleOnStatus = useCallback((status: LifecycleStatus) => { 
  console.log('LifecycleStatus', status); 
}, []); 
 
// omitted for brevity
 
<Transaction
  contracts={contracts}
  onStatus={handleOnStatus}
>
  <TransactionButton />
  <TransactionSponsor />
  <TransactionToast>
    <TransactionToastIcon />
    <TransactionToastLabel />
    <TransactionToastAction />
  </TransactionToast>
</Transaction>

The Lifecycle Status features seven states for the transaction experience.

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: Address[];
      };
    }
  | {
      statusName: 'success'; // if the last mutation attempt was successful
      statusData: {
        transactionReceipts: TransactionReceipt[];
      };
    };

Sponsor with Paymaster capabilities

To sponsor your transactions with Paymaster capabilities, provide the paymasterService object.

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

OnchainKit Paymaster and Bundler endpoint
// omitted for brevity
<Transaction
  capabilities={{ 
    paymasterService: { 
      url: process.env.PAYMASTER_AND_BUNDLER_ENDPOINT, 
    }, 
  }}
  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.

 
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) => console.log('Transaction status:', status)}
    >
      <TransactionButton />
    </Transaction>
  );
}

Components

OnchainKit transaction anatomy component diagram

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