Quickstart

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

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

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:

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:

curl -X GET "https://api.cngn.co/v1/api/balance" \
  -H "Authorization: Bearer cngn_test_xxxxxxxxxxxxx" \
  -H "Content-Type: application/json"

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();

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()

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

{
  "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 for full implementations). The decrypted payload:

[
  {
    "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:

{
  "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 for step-by-step code, or use an official SDK which handles this automatically.

Next steps

Authentication

How API keys, environments, and IP whitelisting work.

Encryption

Encrypt requests and decrypt responses.

API Reference

Explore every endpoint.

Errors

Understand and handle error responses.

Get Started

Integration Guides

Prerequisites

1. Generate your API key

2. Whitelist your IP address

3. Upload your Ed25519 public key

4. Make your first request

5. Decrypt the response

6. Encrypt request bodies

Next steps

Authentication

Encryption

API Reference

Errors

​Prerequisites

​1. Generate your API key

​2. Whitelist your IP address

​3. Upload your Ed25519 public key

​4. Make your first request

​5. Decrypt the response

​6. Encrypt request bodies

​Next steps

Authentication

Encryption

API Reference

Errors

Prerequisites

1. Generate your API key

2. Whitelist your IP address

3. Upload your Ed25519 public key

4. Make your first request

5. Decrypt the response

6. Encrypt request bodies

Next steps