Select Cardano Environment

Testnets and Mainnet

Overview

The Anvil API works across multiple Cardano environments—each serving a unique purpose in your development lifecycle. Whether you’re testing new features with fake ADA or running a full production dApp with real ADA, you’ll point your calls to different base URLs. The API behavior remains consistent, but the domain changes to reflect which network you’re on.

Key Environments:

• Mainnet: Real ADA, real economic value, live user interactions.

• Preprod: A Cardano testnet for safe experimentation (e.g., CIP-68 tokens, CIP-25 minting) without risking real funds.

• Preview: Another testnet, often used to test upcoming features or protocol changes.

Choosing an Environment

Mainnet

• Base URL: https://prod.api.ada-anvil.app

• Use Case: Production-ready calls for real Cardano usage (minting real tokens, CIP-25/68 assets for live dApps).

• Risks: Mistakes cost actual ADA. Validate thoroughly on a testnet before going live.

Preprod

• Base URL: https://preprod.api.ada-anvil.app

• Use Case: Primary test environment. Ideal for verifying transaction building, new CIP-25 or CIP-68 scripts, multi-sig flows, etc.

• Safe: Uses test ADA from a faucet. Great for repeated trials or when you’re unsure about advanced features.

Preview

• Base URL: https://preview.api.ada-anvil.app

• Use Case: Testing future Cardano protocol changes, ensuring your code stays compatible with upcoming releases.

• Similar to Preprod: Uses test ADA but may differ in protocol versions or feature flags.

---

Network IDs (CSL/Technical Details)

If you’re working at a lower level (for instance, with Cardano Serialization Library—CSL), you might see references to network IDs:

• id: 0 means Testnet (applies to Preprod, Preview, or private networks).

• id: 1 means Mainnet.

Anvil’s high-level APIs typically handle network IDs for you. However, if you’re constructing transactions yourself or using raw CSL calls, you may need to specify the correct ID to ensure your transactions are valid.

Note: We’re continually refining Anvil’s tools to abstract away these complexities, so you can focus on your application logic rather than the intricacies of Cardano’s underlying protocol.

---

Getting an Environment-Specific API Key

Each environment requires its own API Key.

• Mainnet Key: For real ADA transactions.

• Preprod Key: For test ADA in the pre-production environment.

• Preview Key: For experimenting with upcoming protocol changes.

Why separate keys? This ensures you won’t accidentally spend real funds when you intended to test, and it keeps usage metrics and rate limits distinct across different project stages.

Steps to acquire keys:

1. Email [e-mail] to request keys for each environment.

2. You’ll receive separate credentials and rate-limit policies for each.

3. Include the correct X-Api-Key in your headers when sending requests (see Authentication guide for details).

---

Development Workflow

1. Local Development

• Start with the Preprod environment to mint tokens, test staking or delegate, and ensure your code works as expected.

• Use tADA from the faucet to simulate transactions.

1. Integration Testing

• Move to the Preview environment if you need to test features not yet live on Mainnet.

• Validate that your application still performs correctly under new protocol rules.

1. Production Deployment

• Once everything is stable and thoroughly tested, switch to the Mainnet domain and use your Mainnet key.

• Ensure your contracts, UTXO handling, and address generation are thoroughly tested on the testnets first.

---

Code Example: Switching Environments Dynamically

Here’s a Node.js snippet showing how you might toggle between environments based on a simple config variable:

// Adjust this to 'preprod', 'preview', or 'mainnet'
const environment = process.env.CARDANO_ENV || "preprod";

const baseUrls = {
  preprod: "https://preprod.api.ada-anvil.app/v2/services",
  preview: "https://preview.api.ada-anvil.app/v2/services",
  mainnet: "https://prod.api.ada-anvil.app/v2/services",
};

// Suppose each environment requires a distinct API key
const apiKeys = {
  preprod: process.env.PREPROD_API_KEY,
  preview: process.env.PREVIEW_API_KEY,
  mainnet: process.env.MAINNET_API_KEY,
};

async function getHealth() {
  const url = `${baseUrls[environment]}/health`;
  const apiKey = apiKeys[environment];

  try {
    const response = await fetch(url, {
      headers: { "X-Api-Key": apiKey },
    });
    console.log(`[${environment.toUpperCase()}] Health:`, await response.json());
  } catch (error) {
    console.error("Error:", error);
  }
}

(async () => {
  await getHealth();
})();

Explanation:

• We store domain URLs and API Keys for each environment.

• We pick the environment via a config variable (CARDANO_ENV).

• If we wanted to run a test suite for both environments, we can easily toggle by changing CARDANO_ENV.

---

FAQ and Troubleshooting

1. Do I need different code for each environment?

• Generally no—only your base URL and API Key change. The rest of your logic remains the same.

1. Why am I getting 401 errors on the testnet but not on Mainnet?

• You might be using your Mainnet key on a testnet endpoint (or vice versa). Ensure you match the key to the environment.

1. What if I need a private cluster?

• Contact us to discuss setting up a private or enterprise environment. We can tailor configurations (network IDs, access controls, node settings) to your needs.

1. Is there any difference in UTXO structure between testnet and Mainnet?

• No—Cardano’s UTXO model works identically across environments. Only the tokens and network ID differ.

---

Next Steps

• Dive into UTXOs vs. Change Address

  • Learn how Cardano’s transaction model differs from account-based blockchains.

• Check Out Our Utilities

  • See how Anvil simplifies common Cardano functions (address derivation, transaction serialization, etc.).

• Ready to Build

  • Head over to our Transaction or NFT & FT guides to start coding real (or test) transactions on Cardano.