FAQ

Getting Started

How to test the Anvil API?

To get started with the Anvil API:

Request API Keys: Email [email protected] to request your API keys: (TODO: will change when portal is running)
- A Preprod key for development and testing
- A Mainnet key with lower rate limits for basic production use

Make Your First API Call: Include your API key in the X-Api-Key header:

curl -X GET \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: YOUR_API_KEY_HERE" \
    https://preprod.api.ada-anvil.app/v2/services/health

Explore the Documentation: See our Build Your First Transaction guide or Cardano Basics if you're new to Cardano.

For more details about authentication, see our Authentication documentation.

What do I need to test on different Cardano environments?

You need two types of API keys: one for testnet environments and one for mainnet, along with the correct endpoint for each network.

The correct endpoints are:

Preprod: https://preprod.api.ada-anvil.app
Preview: https://preview.api.ada-anvil.app
Mainnet: https://prod.api.ada-anvil.app

Is there a difference between testnet and pre-prod, or are they the same thing?

They are related but distinct:

Testnet refers to any non-production Cardano network. Your testnet API key works across all testnet environments (both Preprod and Preview).
Preprod is a specific testnet environment that closely mirrors mainnet's parameters.
Preview is another testnet environment focused on testing future protocol changes.

Both Preprod and Preview use test ADA (not real value), but they may be running different protocol versions. For most testing purposes, Preprod is recommended.

Is my tech compatible with the API?

The Anvil API is designed for maximum flexibility and compatibility across technology stacks:

Language Agnostic: Works with any programming language that can make HTTP requests (JavaScript, Python, Ruby, Go, Java, etc.)
Multiple Interface Options: Supports both REST API and tRPC for type-safe operations
Standard JSON Format: Uses standard JSON for request and response bodies
Simple Authentication: Uses straightforward API key authentication via HTTP headers

This means you can easily integrate the Anvil API with:

Web applications (React, Vue, Angular, etc.)
Mobile apps (React Native, Flutter, native iOS/Android)
Backend servers (Node.js, Python, PHP, Ruby, Java, Rust, Go, C#, etc.)
Command-line tools and scripts

Transaction Building

Can I build and send Cardano transactions entirely from the client-side (browser)?

Yes, but with important security considerations:

Never expose your API key in client-side code - API keys should always be kept on your server side
Be aware of transaction privacy - Direct client-side communication can expose transaction details to network observers or browser extensions

The recommended approach is a hybrid architecture:

Frontend (Browser): Use Weld to connect wallets and handle transaction signing

const wallet = useWallet();
if (wallet.isConnected) {
  // Frontend only handles wallet connection and signing
  const signature = await wallet.handler.signTx(txCbor);
}

Backend (Your Server): Create a secure backend service that:
- Holds your Anvil API key securely
- Communicates with Anvil API to build transactions
- Sends the transaction CBOR to your frontend for signing
- Receives the signature and submits the completed transaction

This architecture ensures your API key remains secure while still leveraging client-side wallet capabilities.

For testing purposes only, you can use the browser console to interact directly with a wallet:

const w = await window.cardano.eternl.enable();
await w.signTx("Your transaction CBOR", true);

How do I sign a transaction to send ADA or NFTs?

For signing transactions:

Browser/Frontend: Use Weld to connect to the user's wallet and request signatures

// First connect to the wallet using Weld
const wallet = useWallet();

if (wallet.isConnected) {
  // Get the wallet to sign your transaction CBOR
  const signature = await wallet.handler.signTx(txCbor);
  // Submit the signed transaction
  // ...
}

Backend/Server: Use Cardano Serialization Library to sign with your private keys
```
// Sign with your private key
tx.sign_and_add_vkey_signature(PrivateKey.from_bech32(privateKey));
```
Other Languages: While the examples above use JavaScript, similar approaches work with other languages:
```
// TODO: add examples for other languages
```

For detailed examples, see our Sign Transaction guide.

Do I need to provide UTXOs when building transactions?

Yes, you need to provide UTXOs when building transactions.

For Testing ONLY (Preprod/Preview): You can optionally let Anvil handle UTXO selection automatically.

// Just provide a change address in test environments
const response = await fetch('https://preprod.api.ada-anvil.app/v2/services/transactions/build', {
  // ...
  body: JSON.stringify({
    changeAddress: 'addr_test...',
    // No UTXOs needed for testing!
    outputs: [/* ... */]
  })
});

For Production (Mainnet): You must explicitly provide UTXOs

// UTXOs are required in production
const response = await fetch('https://prod.api.ada-anvil.app/v2/services/transactions/build', {
  // ...
  body: JSON.stringify({
    utxos: ["8282...", "8282..."],
    changeAddress: 'addr_...',
    outputs: [/* ... */]
  })
});

See Selecting UTXOs for Transactions for more details.

Development Workflow

What's the recommended workflow for developing with Anvil API?

Start with Preprod: Use test ADA from the faucet to develop and test your application
Test edge cases: Ensure your code handles various scenarios correctly
Optional: Test on Preview: If you need to test with upcoming protocol features
Move to Mainnet: Once thoroughly tested, switch to Mainnet endpoints and API key

Remember to keep your environments and API keys separate to avoid accidentally using real ADA during testing.

How do I handle wallet integration in my application?

We strongly recommend using Weld for wallet integration. It provides:

A unified API for multiple Cardano wallets (Eternl, Lace, Flint, etc.)
Simple hooks for React applications
Comprehensive wallet state management
Utilities for common wallet operations

Check our Transaction Overview for a complete flow using Weld and Anvil API.

Smart Contracts and Plutus Scripts

Does the API support smart contract interaction and Plutus scripts?

Yes, Anvil API fully supports Plutus smart contract interactions:

Blueprint Management (CIP-57): Upload your compiled Plutus scripts as blueprints:

# Example: Create a blueprint from an Aiken compiler output
curl -X POST \
    -H "Content-Type: application/json" \
    -H "X-Api-Key: YOUR_API_KEY" \
    https://preprod.api.ada-anvil.app/v2/services/blueprints \
    -d '{"blueprint": {...}}'  # Your Plutus script blueprint

Script Interactions: Once uploaded, you can interact with the contract in transactions by referencing the blueprint and providing required datum/redeemer data.

See our guides on Blueprint Management and example smart contracts like our Simple Mint Smart Contract for practical demonstrations.

API Technical Details

Are there rate limits or usage quotas?

Yes, every API key comes with defined usage limits that protect both you and the service:

Daily Request Limits: Maximum number of requests per 24-hour period, 300k requests per day per key
Requests Per Second (RPS): Maximum throughput rate, 100 requests per second per key

These limits provide important security and stability benefits:

Preventing Unauthorized Use: If your API key is compromised, rate limits minimize potential abuse by capping usage
Cost Control: Helps avoid unexpected charges by setting clear boundaries on API consumption
Service Reliability: Ensures no single client can overload the infrastructure, maintaining high availability for everyone
Attack Mitigation: Protects against DDoS and brute force attacks by throttling excessive requests

If you exceed these limits, the API will respond with Throttled, please try again later.. Your exact quotas are configured when your API key is issued and can be tailored to your application's specific needs.

For higher limits, please contact [email protected].

How is the transaction builder versioned?

The Anvil API transaction builder uses request payload versioning to maintain backward compatibility:

{
  "version": 1,
  // Other request parameters
}

Endpoints that support versioning accept a version field in the request body. This allows endpoints to evolve their functionality while maintaining backward compatibility with existing integrations.

How does Anvil handle blockchain upgrades and protocol changes?

Anvil's infrastructure is updated automatically to support every Cardano protocol upgrade (hard forks, new ledger rules, Plutus enhancements) with zero downtime. You don't need to change your integration—your existing endpoints continue working as the underlying node software is upgraded behind the scenes.

For testing upcoming features, you can point to the Preview endpoints, which run the latest protocol version before it hits Mainnet, so you can verify compatibility in advance.

How do I query blockchain data like transaction history or UTXOs?

The Anvil API focuses primarily on transaction building and submission rather than data querying.

UTXO Management: In test environments, automatic UTXO selection is available
Production Requirements: For mainnet, you must explicitly provide UTXOs
Data Querying: For blockchain exploration (transaction history, balances), we recommend using dedicated blockchain explorers or data APIs like BlockFrost

Note: While not part of our standard API, we do provide specialized blockchain querying and indexing services for enterprise customers. If you need comprehensive blockchain data access for your application, please contact [email protected] to discuss your requirements.

See Selecting UTXOs for Transactions for more information about working with UTXOs in Anvil API.

Support and Feedback

I need help, I have a question or feedback

Send an email to: [email protected]

Join the conversation in Discourse: (coming soon)

PreviousAuthentication NextTroubleshooting

Last updated 1 month ago

Was this helpful?