Authentication

How to access the Anvil API

Authentication

Overview

To interact with the Anvil API, you’ll need an API Key. Think of the API Key as your personal pass to our Cardano infrastructure—each key enforces daily usage limits and burst configurations tailored to your project’s needs.

Important: Treat your API Key like a password. If someone else gains access to it, they can use your quota and potentially access your resources.

---

How to Get Your API Key

Visit our self-serve portal at ada-anvil.io/api-keys to generate your keys instantly. If the portal is unavailable, please email us at [email protected].

---

How to Use Your API Key

You will receive two API keys from Anvil:

• Testnet Key: Use this key for all non-production Cardano environments, including Preprod and Preview.

• Mainnet Key: Use this key exclusively for the Cardano Mainnet environment.

To authenticate your requests, include the appropriate key in the X-Api-Key header.

Basic cURL Example

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

Endpoint: Replace with the environment you want to interact with (e.g., preprod.api.ada-anvil.app, preview.api.ada-anvil.app, etc.).

Method: Varies depending on the API call (GET, POST, etc.).

Headers: Always include your X-Api-Key.

Basic NodeJS Example

async function checkHealth() {
  try {
    const response = await fetch(
      "https://prod.api.ada-anvil.app/v2/services/health",
      {
        headers: {
          "X-Api-Key": "YOUR_API_KEY_HERE",
        },
      },
    );
    console.log("Health Check:", await response.json());
  } catch (error) {
    console.error("Error:", error);
  }
}

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

Python (Requests) Example

import requests

def check_health():
    url = "https://prod.api.ada-anvil.app/v2/services/health"
    headers = {
        "X-Api-Key": "YOUR_API_KEY_HERE",
        "Content-Type": "application/json"
    }

    response = requests.get(url, headers=headers)
    if response.status_code == 200:
        print("Health Check:", response.json())
    else:
        print("Error:", response.status_code, response.text)

check_health()

---

Rate Limits and Quotas

Every API Key has usage limits that define:

• Maximum requests per day

• Requests per second (RPS)

• Burst limits for short-term high-traffic events

These are set during onboarding. If you anticipate large spikes, contact us to adjust your limits.

Tip: Exceeding your rate limits may result in 429 (Throttled, please try again later) errors. In such cases, either reduce your request frequency or upgrade your quota.

---

Best Practices

1. Store Keys Securely

• Use environment variables or a secure key management service.

• Avoid committing keys to public Git repositories.

1. Rotate Keys Periodically

• If you suspect your key has been exposed, email us immediately for revocation and re-issuance.

• Regular key rotation is a good security measure.

1. Use Separate Keys for Each Environment

• Keep your Preprod and Mainnet usage separate for better debugging and resource tracking.

1. Handle Errors Gracefully

• Look for 401 Unauthorized (invalid or missing API key) or Throttled, please try again later..

• Implement retry logic with exponential backoff to avoid overwhelming the service.

---

Common Troubleshooting

401 Unauthorized

Check that you set the X-Api-Key header exactly as provided.

Confirm the key belongs to the specific environment you’re calling.

Throttled, please try again later.

You may have hit your burst or daily limit. Throttle your requests or contact support for higher limits.

Incorrect Endpoint

Verify you’re using the correct URL (Mainnet vs. Preprod vs. Preview). Refer to the Usage page for correct endpoints.

---

Moving Forward

Once your key is active, you can start exploring all the functionality that Anvil’s Cardano APIs offer—everything from minting tokens to submitting transactions and checking balances. Need guidance on environment selection? Head back to our Usage page for a refresher.

Next Steps:

• Dive deeper into Select Cardano Environment to ensure you’re building on the right network for your needs.

• Explore UTXOs vs. Change Address to understand Cardano’s transaction model.

• Build your first transaction or NFT mint using our step-by-step guides in the sidebar.

With your API Key in hand and the right environment chosen, you’re ready to harness the power of Cardano through Anvil—securely and efficiently!