# FAQ

## Getting Started

<details>

<summary><strong>How to test the Anvil API?</strong></summary>

To get started with the Anvil API:

1. **Get Your API Keys**: Visit our self-serve portal at [ada-anvil.io/api-keys](https://ada-anvil.io/api-keys) to generate your keys instantly. If the portal is unavailable, please email us at `hello@ada-anvil.io`.
   * A Preprod key for development and testing
   * A Mainnet key with lower rate limits for basic production use
2. **Make Your First API Call**: Include your API key in the X-Api-Key header:

   ```bash
   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
   ```
3. **Explore the Documentation**: See our [Build Your First Transaction](/guides/transaction/create-basic-transaction.md) guide or [Cardano Basics](/anvil-api/cardano-basics.md) if you're new to Cardano.

For more details about authentication, see our [Authentication](/anvil-api/authentication.md) documentation.

</details>

<details>

<summary><strong>What do I need to test on different Cardano environments?</strong></summary>

> 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/v2/services`
* Preview: `https://preview.api.ada-anvil.app/v2/services`
* Mainnet: `https://prod.api.ada-anvil.app/v2/services`

</details>

<details>

<summary><strong>Is there a difference between testnet and pre-prod, or are they the same thing?</strong></summary>

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.

</details>

<details>

<summary><strong>Is my tech compatible with the API?</strong></summary>

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

</details>

## Transaction Building

<details>

<summary><strong>Can I build and send Cardano transactions entirely from the client-side (browser)?</strong></summary>

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:

1. **Frontend (Browser)**: Use [Weld](https://github.com/Cardano-Forge/weld) to connect wallets and handle transaction signing

   ```javascript
   const wallet = useWallet();
   if (wallet.isConnected) {
     // Frontend only handles wallet connection and signing
     const signature = await wallet.handler.signTx(txCbor);
   }
   ```
2. **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:

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

</details>

<details>

<summary><strong>How do I sign a transaction to send ADA or NFTs?</strong></summary>

For signing transactions:

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

   ```javascript
   // 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
     // ...
   }
   ```

For detailed backend signing examples in multiple languages, see our comprehensive [Sign Transaction guide](https://github.com/Cardano-Forge/anvil-api/blob/main/docs/guides/transaction/signing-transaction.md).

</details>

<details>

<summary><strong>Do I need to provide UTXOs when building transactions?</strong></summary>

Yes, you need to provide UTXOs when building transactions.

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

  ```javascript
  // 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

  ```javascript
  // 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](/guides/transaction/selecting-utxos.md) for more details.

</details>

## Development Workflow

<details>

<summary><strong>What's the recommended workflow for developing with Anvil API?</strong></summary>

1. **Start with Preprod**: Use test ADA from the faucet to develop and test your application
2. **Test edge cases**: Ensure your code handles various scenarios correctly
3. **Optional: Test on Preview**: If you need to test with upcoming protocol features
4. **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.

</details>

<details>

<summary><strong>How do I handle wallet integration in my application?</strong></summary>

We strongly recommend using [Weld](https://github.com/Cardano-Forge/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](/guides/transaction.md) for a complete flow using Weld and Anvil API.

</details>

## Smart Contracts and Plutus Scripts

<details>

<summary><strong>Does the API support smart contract interaction and Plutus scripts?</strong></summary>

Yes, Anvil API fully supports Plutus smart contract interactions:

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

   ```bash
   # 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
   ```
2. **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](/guides/smart-contract/blueprint-management.md) and example smart contracts like our [Simple Mint Smart Contract](/guides/smart-contract/mint-smart-contract.md) for practical demonstrations.

</details>

## API Technical Details

<details>

<summary><strong>Are there rate limits or usage quotas?</strong></summary>

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:

1. **Preventing Unauthorized Use**: If your API key is compromised, rate limits minimize potential abuse by capping usage
2. **Cost Control**: Helps avoid unexpected charges by setting clear boundaries on API consumption
3. **Service Reliability**: Ensures no single client can overload the infrastructure, maintaining high availability for everyone
4. **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 <hello@ada-anvil.io>.

</details>

<details>

<summary><strong>How is the transaction builder versioned?</strong></summary>

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

```json
{
  "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.

</details>

<details>

<summary><strong>How does Anvil handle blockchain upgrades and protocol changes?</strong></summary>

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.

</details>

<details>

<summary><strong>How do I query blockchain data like transaction history or UTXOs?</strong></summary>

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 <hello@ada-anvil.io> to discuss your requirements.

See [Selecting UTXOs for Transactions](/guides/transaction/selecting-utxos.md) for more information about working with UTXOs in Anvil API.

</details>

## Support and Feedback

<details>

<summary><strong>I need help, I have a question or feedback</strong></summary>

Send an email to: <hello@ada-anvil.io>

Join the conversation in Discourse: (coming soon)

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://dev.ada-anvil.io/anvil-api/faq.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.