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

# Quickstart

> Make your first cNGN API request in minutes

This guide walks you through everything needed to make your first successful API call: keys, IP whitelisting, encryption setup, and a balance request.

## Prerequisites

* A verified cNGN merchant account with dashboard access
* Your server's public IP address
* An Ed25519 SSH key pair (used to encrypt API responses to you)

## 1. Generate your API key

From the merchant dashboard, generate an API key for the environment you want to use:

| Environment       | Key prefix     | Purpose                                     |
| ----------------- | -------------- | ------------------------------------------- |
| Test (sandbox)    | `cngn_test...` | Integration and testing; no real funds move |
| Live (production) | `cngn_live...` | Real transactions                           |

<Warning>
  Treat API keys like passwords. Never commit them to source control or expose them in client-side code.
</Warning>

## 2. Whitelist your IP address

The API rejects requests from IP addresses that are not whitelisted with a `403 IP address not whitelisted` error. Add every server IP that will call the API in your dashboard's security settings.

## 3. Upload your Ed25519 public key

Generate an Ed25519 key pair and upload the **public key** to your dashboard for the matching environment:

```bash theme={null}
ssh-keygen -t ed25519 -C "api@yourcompany.com" -f cngn_api_key
```

This produces `cngn_api_key` (private; keep it secret) and `cngn_api_key.pub` (public; upload it). The API encrypts every response payload to this public key; only your private key can decrypt it. Each environment (test/live) has its own SSH key slot; a request fails with `No Test SSH Key found` / `No Live SSH Key found` if the key for that environment is missing.

## 4. Make your first request

`GET /balance` requires no request body, so no request encryption is needed, which makes it a good first call:

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.cngn.co/v1/api/balance" \
    -H "Authorization: Bearer cngn_test_xxxxxxxxxxxxx" \
    -H "Content-Type: application/json"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch("https://api.cngn.co/v1/api/balance", {
    headers: {
      Authorization: `Bearer ${process.env.CNGN_API_KEY}`,
      "Content-Type": "application/json",
    },
  });
  const body = await res.json();
  ```

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

  res = requests.get(
      "https://api.cngn.co/v1/api/balance",
      headers={
          "Authorization": f"Bearer {os.environ['CNGN_API_KEY']}",
          "Content-Type": "application/json",
      },
  )
  body = res.json()
  ```
</CodeGroup>

You'll receive the standard response envelope. The `data` field is an encrypted base64 string:

```json theme={null}
{
  "status": 200,
  "message": "Balance fetched successfully",
  "data": "kJ8vX2mN...base64-encrypted-payload...=="
}
```

## 5. Decrypt the response

Decrypt `data` with your Ed25519 private key (see the [Encryption guide](/guides/encryption) for full implementations). The decrypted payload:

```json theme={null}
[
  {
    "asset_type": "credit_alphanum4",
    "asset_code": "CNGN",
    "balance": "150000.00"
  }
]
```

## 6. Encrypt request bodies

Every `POST`/`PUT` endpoint requires the JSON body to be AES-256-CBC encrypted and wrapped as:

```json theme={null}
{
  "content": "<base64 ciphertext>",
  "iv": "<base64 initialization vector>"
}
```

The encryption key is issued alongside your API key in the dashboard. Requests with plain JSON bodies fail with `Missing encryption data, key, or IV`. See [Encryption](/guides/encryption) for step-by-step code, or use an [official SDK](/sdks) which handles this automatically.

## Next steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/guides/authentication">
    How API keys, environments, and IP whitelisting work.
  </Card>

  <Card title="Encryption" icon="lock" href="/guides/encryption">
    Encrypt requests and decrypt responses.
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/introduction">
    Explore every endpoint.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/guides/errors">
    Understand and handle error responses.
  </Card>
</CardGroup>