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

Currently, we issue API keys manually to ensure each project is configured properly. If you’re interested in accessing the Anvil API, please send an email to [e-mail]. We’ll guide you through the setup process and provide any additional details needed for your specific use case.

Future: Self-Service Portal

We’re working on a self-serve portal to streamline key distribution and management. Once released, you’ll be able to request, rotate, and monitor your keys without waiting for manual approval. Stay tuned!

---

How to Use Your API Key

After receiving your key from Anvil, you’ll need to include it in each request to the API. This is done via a custom header, typically named X-Api-Key.

• Header Name: X-Api-Key

• Header Value: <YOUR_API_KEY>

Because each environment (Mainnet, Preprod, Preview, etc.) may require a distinct key, make sure you’re using the correct one for your chosen environment.

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 (Too Many Requests) 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 429 Too Many Requests (rate limit exceeded).

• 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.

429 Too Many Requests

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!