2. Transaction Lifecycle (including off-chain signatures)

Create, sign, propose, execute, and verify a Safe transaction end-to-end using the Ledger Enterprise Multisig API.

What you'll learn

• Initialize both the Protocol Kit (transaction creation/signing) and the API Kit (proposal/indexing)

• Build and sign an ETH transfer as a Safe transaction

• Propose the signed transaction to the Ledger Multisig Transaction Service

• Execute the transaction on-chain once the signature threshold is met

• Verify execution status through the API

Prerequisites

• Node.js 18+

• A Safe on Sepolia (or another supported chain) where you control at least one owner key

• A private key for a Safe owner: use a testnet-only key

• Sepolia ETH in the Safe for gas and the transfer amount

• viem: used for receipt verification

Install the SDK:

npm install @safe-global/api-kit @safe-global/protocol-kit @safe-global/types-kit viem

Configuration

TypeScript

import SafeApiKitModule from "@safe-global/api-kit";
import SafeModule from "@safe-global/protocol-kit";
import { OperationType } from "@safe-global/types-kit";
import type { MetaTransactionData } from "@safe-global/types-kit";
import { createPublicClient, http } from "viem";
import { sepolia } from "viem/chains";

// ESM interop-safe constructor resolution (required in some runtimes)
const SafeApiKit =
  typeof SafeApiKitModule === "function"
    ? SafeApiKitModule
    : (SafeApiKitModule as unknown as { default: typeof SafeApiKitModule }).default;
const Safe =
  typeof SafeModule === "function"
    ? SafeModule
    : (SafeModule as unknown as { default: typeof SafeModule }).default;

const CHAIN_ID = 11155111n; // Sepolia
const TX_SERVICE_URL = `https://app.multisig.ledger.com/api/safe-transaction-service/${CHAIN_ID}`;
const RPC_URL = "https://ethereum-sepolia-rpc.publicnode.com";
const SAFE_ADDRESS = "0xYourSafeAddress";
const OWNER_PRIVATE_KEY = "your-private-key"; // Testnet only!

Python

curl

The TX_SERVICE_URL points at the Ledger-hosted Transaction Service. Transactions proposed here appear in the Ledger Enterprise Multisig UI.

Supported chains: Ethereum (1), Optimism (10), BSC (56), Polygon (137), Base (8453), Arbitrum (42161), Sepolia (11155111).

Step-by-step

1

Initialize the Protocol Kit and API Kit

The Protocol Kit connects to the blockchain and handles transaction creation and signing. The API Kit talks to the Transaction Service for proposal and querying.

TypeScript

const protocolKit = await Safe.init({
  provider: RPC_URL,
  signer: OWNER_PRIVATE_KEY,
  safeAddress: SAFE_ADDRESS,
});

const apiKit = new SafeApiKit({
  chainId: CHAIN_ID,
  txServiceUrl: TX_SERVICE_URL,
});

const signerAddress = await protocolKit.getSafeProvider().getSignerAddress();

// Verify the signer is an owner
const safeInfo = await apiKit.getSafeInfo(SAFE_ADDRESS);
const isOwner = safeInfo.owners
  .map((o) => o.toLowerCase())
  .includes(signerAddress!.toLowerCase());

if (!isOwner) {
  throw new Error(`${signerAddress} is not an owner of this Safe`);
}

Python

curl

REST API: GET /v1/safes/{address}/ - used internally by getSafeInfo to verify ownership.

2

Create the transaction

Define the transaction parameters and create a Safe transaction object. For a simple ETH transfer, set data to "0x" and operation to Call.

TypeScript

const txData: MetaTransactionData = {
  to: "0xRecipientAddress",
  value: "100000000000000", // 0.0001 ETH in wei
  data: "0x",
  operation: OperationType.Call,
};

const safeTransaction = await protocolKit.createTransaction({
  transactions: [txData],
});

Python

curl

The Protocol Kit automatically sets the nonce, safeTxGas, baseGas, gasPrice, gasToken, and refundReceiver fields based on the current Safe state.

3

Sign the transaction

Compute the Safe transaction hash and sign it with the owner's private key. This produces an off-chain (EIP-712) signature with no gas is spent.

TypeScript

const safeTxHash = await protocolKit.getTransactionHash(safeTransaction);
const signature = await protocolKit.signHash(safeTxHash);

Python

curl

The safeTxHash is the unique identifier for this transaction within the Safe. It is not an on-chain transaction hash.

4

Propose the transaction

Submit the signed transaction to the Transaction Service. This stores it off-chain and makes it visible to other owners in the Ledger Multisig UI.

TypeScript

await apiKit.proposeTransaction({
  safeAddress: SAFE_ADDRESS,
  safeTransactionData: safeTransaction.data,
  safeTxHash,
  senderAddress: signerAddress!,
  senderSignature: signature.data,
});

Python

curl

REST API: POST /v1/safes/{address}/multisig-transactions/ - the request body includes the full transaction data, the safeTxHash, the sender address, and the signature.

After proposing, the transaction is visible in the Ledger Enterprise Multisig UI and other owners can sign the transaction.

5

Check confirmations and execute

Retrieve the pending transaction, check if enough signatures have been collected to meet the threshold, and execute on-chain if ready.

TypeScript

const pendingTx = await apiKit.getTransaction(safeTxHash);
const confirmationCount = pendingTx.confirmations?.length ?? 0;

if (confirmationCount >= pendingTx.confirmationsRequired) {
  const executionResult = await protocolKit.executeTransaction(pendingTx);
  console.log("Transaction hash:", executionResult.hash);
} else {
  console.log(
    `Need ${pendingTx.confirmationsRequired - confirmationCount} more signature(s)`
  );
}

Python

curl

REST API: GET /v1/multisig-transactions/{safeTxHash}/ - retrieves a single transaction by its Safe transaction hash, including all collected confirmations.

If the threshold is not yet met, other owners can confirm using:

TypeScript

await apiKit.confirmTransaction(safeTxHash, theirSignature.data);

Python

curl

REST API: POST /v1/multisig-transactions/{safeTxHash}/confirmations/

6

Verify execution

After execution, query the Transaction Service to confirm the transaction was indexed as executed and successful.

TypeScript

// Wait for the Transaction Service to index the execution
await new Promise((resolve) => setTimeout(resolve, 10_000));

// Re-fetch the exact tx by safeTxHash (safer than "latest tx")
const updated = await apiKit.getTransaction(safeTxHash);
console.log("Executed:", updated.isExecuted);
console.log("Successful:", updated.isSuccessful);
console.log("On-chain hash:", updated.transactionHash);

Python

curl

Key concepts

Off-chain signatures, on-chain execution. Safe transactions use a two-phase model:

• Propose: The transaction data and an owner's signature are submitted to the Transaction Service (off-chain, no gas).

• Execute: Once enough signatures meet the threshold, any account can submit the transaction on-chain (costs gas).

This means a 3-of-5 Safe only pays gas once - when the final executor submits all collected signatures in a single on-chain call.

For the full guide, see Transactions with Off-chain Signatures.

Tips and pitfalls

• Indexing lag. After executeTransaction returns, the Transaction Service may take 10–60 seconds to index the receipt. If you query immediately, isExecuted may still be false and isSuccessful may be null. The on-chain transaction is confirmed. The indexer catches up within a minute or two.

• executeTransaction can return a hash for a reverted tx. The Protocol Kit returns a transaction hash even if the on-chain transaction reverts. Always check the receipt status independently.

TypeScript

const publicClient = createPublicClient({
  chain: sepolia,
  transport: http(RPC_URL),
});

const receipt = await publicClient.waitForTransactionReceipt({
  hash: executionResult.hash as `0x${string}`,
  timeout: 120_000,
});

if (receipt.status === "reverted") {
  throw new Error("Transaction reverted on-chain");
}

Python

curl

• Signer must be an owner. The proposeTransaction call will fail if senderAddress is not a current owner (or delegate) of the Safe. Verify ownership before proposing.

• Nonce management. The Protocol Kit automatically picks the next nonce. If you need to queue transactions in a specific order, pass options: { nonce } to createTransaction.

Next steps

3. Batch Transactions