Skip to main content
GET
/
v3
/
account
/
balance
Get Account Balance
curl --request GET \
  --url https://api.oneclickdz.com/v3/account/balance \
  --header 'X-Access-Token: <api-key>'
{
  "success": true,
  "data": {
    "balance": 123
  },
  "meta": {
    "timestamp": "<string>"
  }
}

​
Overview

Get your current account balance in Algerian Dinar (DZD). The balance represents available funds that can be used for top-ups, orders, and other services.
When your balance reaches a low threshold, a notification will be sent to your registered email address.

​
Response

​
success
boolean
required
true for successful requests
​
data
object
required
​
meta
object

​
Example Request

curl --request GET \
  --url https://api.oneclickdz.com/v3/account/balance \
  --header 'X-Access-Token: YOUR_API_KEY'

​
Example Response

{
  "success": true,
  "data": {
    "balance": 1326.13
  },
  "meta": {
    "timestamp": "2025-10-29T00:35:58.710Z"
  }
}

​
Use Cases

Pre-Transaction Check

Verify sufficient funds before processing orders

Balance Display

Show current balance in your application UI

Low Balance Alerts

Monitor balance and alert when running low

Financial Reports

Track balance changes over time

​
Integration Examples

​
Pre-Transaction Validation

async function canProcessTransaction(amount) {
  const response = await fetch(
    "https://api.oneclickdz.com/v3/account/balance",
    {
      headers: { "X-Access-Token": API_KEY },
    }
  );

  const data = await response.json();

  if (!data.success) {
    throw new Error("Failed to check balance");
  }

  const balance = data.data.balance;

  if (balance < amount) {
    throw new Error(
      `Insufficient balance. Required: ${amount} DZD, Available: ${balance} DZD`
    );
  }

  return true;
}

// Usage
try {
  await canProcessTransaction(500);
  // Proceed with transaction
} catch (error) {
  console.error(error.message);
  // Show error to user
}

​
Balance Monitoring

class BalanceMonitor {
  constructor(apiKey, lowBalanceThreshold = 1000) {
    this.apiKey = apiKey;
    this.lowBalanceThreshold = lowBalanceThreshold;
    this.lastBalance = null;
  }

  async checkBalance() {
    const response = await fetch(
      "https://api.oneclickdz.com/v3/account/balance",
      {
        headers: { "X-Access-Token": this.apiKey },
      }
    );

    const data = await response.json();

    if (!data.success) {
      console.error("Failed to check balance:", data.error);
      return;
    }

    const currentBalance = data.data.balance;

    // Check for low balance
    if (currentBalance < this.lowBalanceThreshold) {
      this.onLowBalance(currentBalance);
    }

    // Check for significant changes
    if (this.lastBalance !== null) {
      const change = currentBalance - this.lastBalance;

      if (Math.abs(change) > 100) {
        this.onBalanceChange(change, currentBalance);
      }
    }

    this.lastBalance = currentBalance;
    return currentBalance;
  }

  onLowBalance(balance) {
    console.warn(`⚠️ Low balance alert: ${balance} DZD`);
    // Send notification to admin
    this.sendNotification({
      type: "low_balance",
      balance: balance,
      threshold: this.lowBalanceThreshold,
    });
  }

  onBalanceChange(change, newBalance) {
    const changeType = change > 0 ? "increased" : "decreased";
    console.log(
      `Balance ${changeType} by ${Math.abs(
        change
      )} DZD. New balance: ${newBalance} DZD`
    );
  }

  sendNotification(data) {
    // Implement your notification logic
    console.log("Notification:", data);
  }

  startMonitoring(intervalMinutes = 5) {
    // Initial check
    this.checkBalance();

    // Periodic checks
    setInterval(() => {
      this.checkBalance();
    }, intervalMinutes * 60 * 1000);
  }
}

// Usage
const monitor = new BalanceMonitor(API_KEY, 1000);
monitor.startMonitoring(5); // Check every 5 minutes

​
Balance Caching

class BalanceCache {
  constructor(apiKey, cacheSeconds = 30) {
    this.apiKey = apiKey;
    this.cacheSeconds = cacheSeconds;
    this.cache = {
      balance: null,
      timestamp: 0,
    };
  }

  async getBalance(forceRefresh = false) {
    const now = Date.now();
    const cacheAge = (now - this.cache.timestamp) / 1000;

    // Return cached value if valid
    if (
      !forceRefresh &&
      this.cache.balance !== null &&
      cacheAge < this.cacheSeconds
    ) {
      return this.cache.balance;
    }

    // Fetch fresh balance
    const response = await fetch(
      "https://api.oneclickdz.com/v3/account/balance",
      {
        headers: { "X-Access-Token": this.apiKey },
      }
    );

    const data = await response.json();

    if (!data.success) {
      throw new Error(`Failed to fetch balance: ${data.error.message}`);
    }

    // Update cache
    this.cache = {
      balance: data.data.balance,
      timestamp: now,
    };

    return this.cache.balance;
  }

  invalidateCache() {
    this.cache.timestamp = 0;
  }
}

// Usage
const balanceCache = new BalanceCache(API_KEY, 30);

// First call - fetches from API
const balance1 = await balanceCache.getBalance();

// Second call within 30 seconds - returns cached value
const balance2 = await balanceCache.getBalance();

// Force refresh
const balance3 = await balanceCache.getBalance(true);

​
Best Practices

Always verify sufficient balance before initiating transactions
// ✅ Good
const balance = await getBalance();
if (balance >= requiredAmount) {
  await sendTopUp(...);
}

// ❌ Bad
await sendTopUp(...); // Might fail with NO_BALANCE error
Cache balance for 30-60 seconds to reduce API calls javascript // Cache balance but invalidate after transactions const balance = await balanceCache.getBalance(); await sendTopUp(...); balanceCache.invalidateCache(); // Refresh after transaction
Implement proper error handling
async function getSafeBalance() {
  try {
    const response = await fetch('https://api.oneclickdz.com/v3/account/balance', {
      headers: { 'X-Access-Token': API_KEY }
    });
    
    const data = await response.json();
    
    if (!data.success) {
      console.error('Balance check failed:', data.error);
      return null;
    }
    
    return data.data.balance;
  } catch (error) {
    console.error('Network error:', error);
    return null;
  }
}
Set up alerts for low balance
const LOW_BALANCE_THRESHOLD = 1000;

async function checkAndAlert() {
  const balance = await getBalance();
  
  if (balance < LOW_BALANCE_THRESHOLD) {
    await sendAlert({
      type: 'low_balance',
      balance: balance,
      message: `Balance is low: ${balance} DZD`
    });
  }
}

​
Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_ACCESS_TOKEN",
    "message": "The provided access token is invalid"
  },
  "requestId": "req_abc123"
}

{
  "success": false,
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Developer was notified and will check shortly"
  },
  "requestId": "req_abc123"
}

List Transactions

View transaction history

Send Mobile Top-Up

Send a mobile top-up