cNGN SDK

Rust client for the cNGN API.

Installation

Add the SDK to your project:

cngn-sdk = { path = "../cngn-sdk" }

Usage

use cngn_sdk::client::Client;

let client = Client::from_env()?;
let balance = client.wallet_manager().balance().await?;

For local testing, the SDK can load CNGN_KEY, CNGN_ENCRYPTION_KEY, and CNGN_PRIVATE_KEY from the process environment or a local .env file. The private key should be the complete OpenSSH Ed25519 private key, including its BEGIN OPENSSH PRIVATE KEY and END OPENSSH PRIVATE KEY lines:

let client = Client::from_env()?;
let balance = client.wallet_manager().balance().await?;

You can also provide the encryption values directly:

let client = Client::new("API_KEY")
    .with_security("encryption_key", "openssh_private_key");

Run the wallet balance smoke test with:

cargo run --example smoke

To inspect AES encryption with a safe fake key:

cargo run --example encryption

Testing

Run all unit and offline integration tests with:

cargo test

The integration test starts a temporary local HTTP server and checks every current service method without an API key, encryption key, quota, or IP whitelist:

cargo test --test sdk -- --nocapture

The encryption example prints the plaintext, base64 encrypted content, base64 IV, and decrypted plaintext:

cargo run --example encryption

The encrypted content and IV are expected to change every run because a new random IV is generated. The live smoke test needs real environment values and an allowed source IP:

cargo run --example smoke

For automatic reruns after source changes, install cargo-watch once and run:

cargo install cargo-watch
cargo watch -x 'run --example smoke'

The smoke test prints configuration, network, API, and response parsing errors without printing either secret.

Services

Wallet manager

Provides balances, transactions, supported networks, wallet whitelisting, and whitelisted addresses.

let wallet = client.wallet_manager();
let balance = wallet.balance().await?;
let transactions = wallet.transactions(1, 20).await?;

Deposit

Provides virtual accounts, temporary virtual accounts, bank lookup, account verification, and settlement bank updates.

let deposit = client.deposit();
let accounts = deposit.virtual_accounts().await?;

Redemptions

Provides cNGN redemption to a bank account.

let redemption = client.redemptions();

Onchain transfer

Provides wallet withdrawals, withdrawal verification, bridge quotes, and bridging.

let transfer = client.onchain_transfer();

Authentication

The client sends the API key as a Bearer token. The API also requires a whitelisted source IP.

API failures are returned as typed Error::Api values. Match on ApiErrorKind for authentication, encryption, validation, rate-limit, and business-logic failures. Error::is_retryable() is useful for network, 429, service-availability, and 5xx failures.

Base URL

The default base URL is https://api.cngn.co/v1/api.

For testing or a custom deployment:

---

let client = Client::with_base_url(
    "cngn_live_api_key",
    "https://api.cngn.co/v1/api",
).with_security("encryption_key", "openssh_private_key");

Encryption

The SDK encrypts request bodies with AES-256-CBC. The key is SHA-256 hashed, the IV is random for every request, and both encrypted values are base64 encoded in the content and iv fields expected by cNGN. Encrypted responses are opened with the configured OpenSSH Ed25519 private key.