Transaction

Overview of Anvil API Cardano Transaction Builder capabilities

Introduction

Cardano transactions are the fundamental way to move value and interact with the blockchain, whether it's moving ADA, native tokens, and NFTs. Or it's interacting with smart contracts. The Anvil API simplifies transaction creation with a flexible interface that supports:

• Simple to complex outputs - from basic ADA transfers to multi-asset transactions with multiple recipients

• Input methods - using changeAddress and UTXOs to source funds

• Complete transaction lifecycle - building, signing, and submitting in a streamlined workflow

This documentation covers the various transaction types, payload structures, and best practices for creating transactions with the Anvil API.

The Basic Flow

1. BUILD: We structure a simple payload with changeAddress, utxos, and outputs

2. SIGN: We sign the transaction with your preferred signing method (See Signing Transactions)

3. SUBMIT: We send the signed transaction to the Anvil API's transaction submit endpoint

4. CONFIRM: We handle the response from the submit endpoint

Transaction Flow Overview

Below is a sequence diagram that illustrates the basic flow of a transaction between your application and the Anvil API.

Breakdown of the Basic Flow

The above flow diagram illustrates the basic flow of a transaction. The following sections will break down each step in detail. As you can see there are two API calls that are involved in the basic flow: Build and Submit. The Build API call is used to build a transaction, and the Submit API call is used to submit a transaction after the user or application has signed it.

1. Building Transaction: Defining Addresses, UTXOs, and Outputs

The Build (POST /transaction/build)API call is used to build a transaction. This call requires a payload that includes the sender address for change, UTXOs for inputs, and outputs.

// Structure for the transaction build request
const buildBody = {
  // Sender address for change
  changeAddress: "addr_sender...",
  
  // UTXOs for inputs (either address or array of CBOR-encoded UTXOs)
  // For CIP-30 wallets: await wallet.getUtxos()
  utxos: "UTXOS", 
  
  // Where to send the ADA, assets, and amounts
  outputs: [
    {
      address: "addr_recipient...",
      lovelace: 10_000_000, // 10 ADA
    },
  ],
  //Add additional outputs here.
};

// Send the build request
const buildResponse = await fetch(
  "https://preprod.api.ada-anvil.app/v2/services/transactions/build",
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Api-Key": "YOUR_API_KEY",
    },
    body: JSON.stringify(buildBody),
  }
);

const buildData = await buildResponse.json();

Build Response Structure

// After successful build
{
  "hash": "TRANSACTION_HASH",

  // Complete transaction is preferred for signing most transactions.
  "complete": "TRANSACTION_CBOR", 
  
  // Stripped transaction is preferred for minting operations (NFTs/tokens).
  // This is because we want to hide metadata from the client. 
  "stripped": "STRIPPED_CBOR", 
  
  // The witness data component
  "witnessSet": "WITNESS_SET_CBOR"
}

Important Warning:

• Use the complete format when you don't care about hiding metadata from the frontend client.

• For minting operations (NFTs/tokens), only exposing the stripped format of your build response helps hide metadata from the frontend client. The complete format will include those attributes allowing users to see the metadata before the transaction is submitted.

2. Sign the Transaction

Sign the transaction with your preferred signing method (See Signing Transactions). This can be done using a CIP-30 compatible wallet, or by using a private key in your application, or by using a hardware wallet. We recommend using the @ada-anvil/weld wallet connector for a seamless experience handling interactions with Cardano wallets.

3. Submit the Signed Transaction

Once you have the signatures, we can submit POST /transaction/submit the transaction in two ways:

1. Embed signatures in transaction: You can embed the signatures in the transaction. This is helpful when you are signing a transaction in a backend server (using CSL). Otherwise, option 2 is recommended.

2. Separate transaction and signatures: You can separate the transaction and signatures and send them to the API separately.

// Option 1: Submit with signatures embedded in transaction.
const submitBody = {
  transaction: "SIGNED_TRANSACTION_CBOR" 
};

// Option 2: Submit with separate transaction and signatures
const submitBody = {
  transaction: "UNSIGNED_TRANSACTION_CBOR", 
  signatures: ["SIGNATURE_1", "SIGNATURE_2"] // Array of signatures
};

Submit Response Structure

// After successful submit
{
  "hash": "TRANSACTION_HASH" // The transaction ID on the blockchain
}

Cardano is Deterministic: The transaction hash returned by the build endpoint is the same hash that will appear on-chain. Unlike some other blockchains, Cardano's eUTXO model allows for deterministic transaction creation - the transaction ID is calculated before submission and remains unchanged when confirmed on the blockchain. This feature enables reliable transaction tracking from creation through confirmation.

---

Best Practices

• Test on Preprod first to avoid risking real ADA.

• Handle Errors gracefully: watch for 400 (bad request), 401 (unauthorized), or 429 (rate limit) responses.

• Use CIP-30 for a user-friendly Web3 experience: fetch utxos and changeAddress directly from the user's connected wallet.

• Validate JSON: Ensure your payload is correctly formed—typos in keys like lovelace can cause failures.

• Include sufficient ADA: When sending native assets, include at least 2 ADA per output (due to min-UTXO requirements).

• Verify addresses: Always double-check recipient addresses before submitting transactions.

• Keep API keys secure: Never expose your API keys in client-side code.

---

Transaction Builder Examples and Next Steps

Now that you have a basic understanding of how to send a transaction, explore how the Anvil API is flexible and can handle many types of transactions. Wether you are sending ADA and/or assets to multiple recipients, adding metadata to transactions, or handling multi-signature transactions, the Anvil API takes advantage of the full power of transactions on Cardano.

Review our guides below for more details. They provide practical examples of how to use the Anvil API transaction builder:

Create Basic Transaction

Create Custom Transaction

Create Transaction with Metadata (CIP-20)

https://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/transaction/multi-signature-transaction/README.md