> ## Documentation Index
> Fetch the complete documentation index at: https://nexus.gerowallet.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Make your first API call in under 5 minutes

Get up and running with Gero Nexus in a few minutes. This guide walks you through creating an API key and making your first request.

## Prerequisites

* A Nexus account with an active plan
* Basic knowledge of HTTP requests
* A tool to make API calls (cURL, Postman, or code)

## Step 1: Create an API Key

Programmatic access uses an **API key** sent in the `X-Api-Key` header. API keys are long-lived
(they don't expire every hour like a session token), which makes them the right credential for
servers, scripts, and integrations.

1. Sign in to the [dashboard](https://nexus.gerowallet.io/dashboard/api-keys)
2. Create an API key and choose its network (e.g. Cardano Mainnet, Midnight Mainnet)
3. Copy the key — it's shown once and looks like `nxs_uYc...`

<Warning>
  Send the key in the **`X-Api-Key`** header. Do **not** put it in `Authorization: Bearer` —
  that header is reserved for JWT session tokens, and an API key there returns **401
  Unauthorized**. (See [Authentication](/docs/authentication) for the difference.)
</Warning>

## Step 2: Make Your First Request

Let's fetch the latest block from the Cardano blockchain.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://nexus.gerowallet.io/api/blocks/latest" \
    -H "X-Api-Key: nxs_your_api_key_here"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://nexus.gerowallet.io/api/blocks/latest', {
    headers: {
      'X-Api-Key': 'nxs_your_api_key_here'
    }
  });

  const latestBlock = await response.json();
  console.log(latestBlock);
  ```

  ```python Python theme={null}
  import requests

  url = "https://nexus.gerowallet.io/api/blocks/latest"
  headers = {
      "X-Api-Key": "nxs_your_api_key_here"
  }

  response = requests.get(url, headers=headers)
  latest_block = response.json()
  print(latest_block)
  ```

  ```rust Rust theme={null}
  use reqwest;
  use serde_json::Value;

  #[tokio::main]
  async fn main() -> Result<(), Box<dyn std::error::Error>> {
      let client = reqwest::Client::new();

      let response = client
          .get("https://nexus.gerowallet.io/api/blocks/latest")
          .header("X-Api-Key", "nxs_your_api_key_here")
          .send()
          .await?;

      let latest_block: Value = response.json().await?;
      println!("{:#?}", latest_block);

      Ok(())
  }
  ```
</CodeGroup>

### Expected Response

```json theme={null}
{
  "hash": "4e1ba9d3e6f6b5c8d9a7f3e1c2b4a5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
  "height": 8765432,
  "number": 8765432,
  "time": 1738713600,
  "slot": 123456789,
  "epoch": 450,
  "epoch_slot": 123456,
  "slot_leader": "pool1abcdef123456789",
  "size": 24567,
  "tx_count": 42,
  "output": "34567890123456",
  "fees": "456789",
  "previous_block": "3d0ca8e2f5b4c7a6e8d9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0",
  "next_block": null,
  "confirmations": 0
}
```

<Check>
  **Success!** You've made your first API call to Gero Nexus.
</Check>

## Step 3: Explore More Endpoints

Now that you've made your first call, try these common endpoints:

<CardGroup cols={2}>
  <Card title="Get Block by Hash" icon="cube">
    ```bash theme={null}
    GET /api/blocks/{hash}
    ```

    Fetch detailed information about a specific block
  </Card>

  <Card title="Get Transaction" icon="exchange-alt">
    ```bash theme={null}
    GET /api/transactions/{txHash}
    ```

    Retrieve transaction details and UTXOs
  </Card>

  <Card title="Get Address Info" icon="wallet">
    ```bash theme={null}
    GET /api/addresses/{address}
    ```

    Check balance and transactions for an address
  </Card>

  <Card title="Get Latest Epoch" icon="clock">
    ```bash theme={null}
    GET /api/epoch/latest
    ```

    Get current epoch information
  </Card>
</CardGroup>

## Using the Interactive Playground

Want to test endpoints without writing code? Every page in the [API Reference](/docs/api-reference) has a built-in playground:

1. Open an endpoint in the [API Reference](/docs/api-reference)
2. Enter your API key in the `X-Api-Key` field
3. Fill in any parameters
4. Click **"Send"** to see the live response

<Tip>
  The playground is great for exploring the API and testing different parameters before writing code.
</Tip>

## Best Practices

<AccordionGroup>
  <Accordion title="Secure Your API Key" icon="lock">
    * Never commit API keys to version control
    * Store keys in environment variables or a secrets manager
    * Rotate keys from the dashboard if one is exposed
    * Scope each key to the network it needs (mainnet keys can't query preprod)
  </Accordion>

  <Accordion title="Handle Rate Limits" icon="gauge">
    * Requests are bounded by a monthly quota and a per-second limit (see [Rate Limits](/docs/concepts/rate-limits))
    * On a 429, honor the `Retry-After` header before retrying
    * Watch `X-RateLimit-Remaining` and monitor your usage in the dashboard
    * Cache responses when possible
  </Accordion>

  <Accordion title="Error Handling" icon="triangle-exclamation">
    Always check response status codes:

    * `200` - Success
    * `400` - Bad request (invalid parameters)
    * `401` - Unauthorized (missing/invalid API key, or key in the wrong header)
    * `402` - Add-on required for this endpoint
    * `404` - Resource not found
    * `429` - Rate limit exceeded
    * `500` - Server error (contact support)

    See [Error Handling](/docs/concepts/error-handling) for the full error contract.
  </Accordion>
</AccordionGroup>

## Example: Building a Simple Balance Checker

Here's a complete example that checks the balance of a Cardano address:

<CodeGroup>
  ```javascript JavaScript (Node.js) theme={null}
  // balance-checker.js

  const API_BASE = 'https://nexus.gerowallet.io';
  const API_KEY = process.env.NEXUS_API_KEY; // nxs_...

  async function getAddressBalance(address) {
    const response = await fetch(`${API_BASE}/api/addresses/${address}`, {
      headers: { 'X-Api-Key': API_KEY }
    });

    if (!response.ok) {
      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
    }

    const data = await response.json();

    // Convert lovelace to ADA (1 ADA = 1,000,000 lovelace)
    const adaBalance = parseInt(data.balance) / 1_000_000;

    console.log(`Address: ${address}`);
    console.log(`Balance: ${adaBalance.toFixed(2)} ADA`);

    return data;
  }

  // Example usage
  const address = 'addr1q9xyz...'; // Replace with actual address
  getAddressBalance(address).catch((e) => console.error('Error:', e.message));
  ```

  ```python Python theme={null}
  # balance_checker.py
  import os
  import requests

  API_BASE = 'https://nexus.gerowallet.io'
  API_KEY = os.environ['NEXUS_API_KEY']  # nxs_...


  def get_address_balance(address):
      """Get balance for a Cardano address"""
      response = requests.get(
          f'{API_BASE}/api/addresses/{address}',
          headers={'X-Api-Key': API_KEY}
      )
      response.raise_for_status()

      data = response.json()

      # Convert lovelace to ADA (1 ADA = 1,000,000 lovelace)
      ada_balance = int(data['balance']) / 1_000_000

      print(f"Address: {address}")
      print(f"Balance: {ada_balance:.2f} ADA")

      return data


  # Example usage
  if __name__ == "__main__":
      address = "addr1q9xyz..."  # Replace with actual address
      get_address_balance(address)
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication Guide" icon="key" href="/docs/authentication">
    API keys vs. session tokens, and security best practices
  </Card>

  <Card title="API Reference" icon="book" href="/docs/api-reference">
    Explore all available endpoints
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/docs/concepts/rate-limits">
    Understand rate limiting and quotas
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation" href="/docs/concepts/error-handling">
    Learn how to handle API errors gracefully
  </Card>
</CardGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Join Discord" icon="discord" href="https://discord.gg/UY75d23jvK">
    Chat with our team and community
  </Card>

  <Card title="Contact Support" icon="envelope" href="https://gerowallet.io/support">
    Email us for assistance
  </Card>
</CardGroup>

***

**Congratulations!** You're now ready to build with Gero Nexus. Check out the [API Reference](/docs/api-reference) for a full list of endpoints.