Balance API

Overview

The Balance API allows you to check your current available balance for using DeCaptcha services. Monitoring your balance is essential to ensure uninterrupted service for your captcha solving needs.

Your account balance is deducted automatically for each captcha solving request. When your balance falls below threshold, our system will send you an email notification.

Check Balance

GET

/api/balance

Request

Headers

Name	Required	Description
`x-api-key`	Yes	Your API key

Response

Success Response (200 OK)


{
  "isSuccess": true,
  "statusCode": 200,
  "errorMessage": null,
  "data": "1250.75"
}

Response Fields

Field	Type	Description
`isSuccess`	boolean	Indicates if the request was successful
`statusCode`	number	HTTP status code
`errorMessage`	string	Error message (null if successful)
`data`	string	Your current account balance as a formatted string

Error Response


{
  "isSuccess": false,
  "statusCode": 401,
  "errorMessage": "Invalid API key",
  "data": null
}

Error Codes

Status Code	Message	Description
401	Unauthorized	Invalid API key or not provided
500	Internal server error	Something went wrong on our end

Balance Management

Your DeCaptcha account balance is managed automatically by our system. Here's how it works:

Automatic Deductions

Per-Request Deduction: Each time you make a captcha solving request, the cost is automatically deducted from your balance.
Cost Variations: Different captcha types may have different costs. The exact cost per request is configured in your account settings.

Topping Up Your Balance

To add funds to your account, please use the following method:

Contact Support: Please contact our support team for any top up requirements.

Important: The Balance API is read-only. To add funds to your account, please contact our support team.

Balance Alerts

Our system automatically monitors your balance and sends alerts when it falls below your configured threshold.

Low Balance Notification

When your balance falls below the threshold set in your merchant account, our system will automatically send an email notification to all registered users associated with your merchant account.

Code Examples


using System;
using System.Net.Http;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class BalanceExample
{
    private static readonly HttpClient client = new HttpClient();
    private const string ApiUrl = "/api/balance";
    private const string ApiKey = "YOUR_API_KEY";

    public static async Task CheckBalance()
    {
        try
        {
            // Prepare request with API key header
            client.DefaultRequestHeaders.Clear();
            client.DefaultRequestHeaders.Add("x-api-key", ApiKey);

            // Send GET request
            var response = await client.GetAsync(ApiUrl);
            response.EnsureSuccessStatusCode();

            var responseString = await response.Content.ReadAsStringAsync();

            // Parse response
            dynamic result = JsonConvert.DeserializeObject(responseString);

            if (result.isSuccess)
            {
                string balanceStr = result.data;

                // Convert string balance to decimal
                if (decimal.TryParse(balanceStr, out decimal balance))
                {
                    Console.WriteLine($"Current Balance: {balance}");
                    return balance;
                }
                else
                {
                    throw new Exception($"Could not parse balance: {balanceStr}");
                }
            }
            else
            {
                throw new Exception($"Error: {result.errorMessage}");
            }
        }
        catch (HttpRequestException ex)
        {
            Console.WriteLine($"HTTP Request Error: {ex.Message}");
            throw;
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error: {ex.Message}");
            throw;
        }
    }

    // Example implementation of a low balance monitor
    public static async Task MonitorBalance(decimal threshold = 100m)
    {
        try
        {
            decimal currentBalance = await CheckBalance();

            if (currentBalance < threshold)
            {
                // Implement your low balance alert mechanism here
                Console.WriteLine($"WARNING: Balance below threshold! Current balance: {currentBalance}");

                // Example: Send email notification
                // await SendLowBalanceAlert(currentBalance, threshold);
            }
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Balance monitoring failed: {ex.Message}");
        }
    }
}


import requests
import json

API_URL = "/api/balance"
API_KEY = "YOUR_API_KEY"

def check_balance():
    try:
        # Prepare headers
        headers = {
            "x-api-key": API_KEY
        }

        # Make request
        response = requests.get(API_URL, headers=headers)
        response.raise_for_status()  # Raise exception for 4XX/5XX responses

        result = response.json()

        if result["isSuccess"]:
            balance_str = result["data"]

            # Convert string balance to float
            try:
                balance = float(balance_str.replace(',', ''))
                print(f"Current Balance: {balance}")
                return balance
            except ValueError:
                raise Exception(f"Could not parse balance: {balance_str}")
        else:
            raise Exception(f"Error: {result['errorMessage']}")

    except requests.exceptions.RequestException as e:
        print(f"HTTP Request Error: {e}")
        raise
    except Exception as e:
        print(f"Error: {e}")
        raise

# Example implementation of a low balance monitor
def monitor_balance(threshold=100.0):
    try:
        current_balance = check_balance()

        if current_balance < threshold:
            # Implement your low balance alert mechanism here
            print(f"WARNING: Balance below threshold! Current balance: {current_balance}")

            # Example: Send email notification
            # send_low_balance_alert(current_balance, threshold)

    except Exception as e:
        print(f"Balance monitoring failed: {e}")

# Example usage
if __name__ == "__main__":
    try:
        balance = check_balance()
        monitor_balance(threshold=200.0)
    except Exception as e:
        print(str(e))


// Balance API Example

async function checkBalance() {
  const API_URL = "/api/balance";
  const API_KEY = "YOUR_API_KEY";

  try {
    // Send request
    const response = await fetch(API_URL, {
      method: 'GET',
      headers: {
        'x-api-key': API_KEY
      }
    });

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

    const result = await response.json();

    if (result.isSuccess) {
      const balanceStr = result.data;

      // Convert string balance to number
      const balance = parseFloat(balanceStr.replace(/,/g, ''));

      if (isNaN(balance)) {
        throw new Error(`Could not parse balance: ${balanceStr}`);
      }

      console.log(`Current Balance: ${balance}`);
      return balance;
    } else {
      throw new Error(`Error: ${result.errorMessage}`);
    }
  } catch (error) {
    console.error('Failed to check balance:', error);
    throw error;
  }
}

// Example implementation of a low balance monitor
async function monitorBalance(threshold = 100) {
  try {
    const currentBalance = await checkBalance();

    if (currentBalance < threshold) {
      // Implement your low balance alert mechanism here
      console.warn(`WARNING: Balance below threshold! Current balance: ${currentBalance}`);

      // Example: Display alert to user
      if (typeof document !== 'undefined') {
        const alertDiv = document.createElement('div');
        alertDiv.className = 'alert alert-danger';
        alertDiv.innerHTML = `
                            Low Balance Alert! 
          Your current balance (${currentBalance}) is below the threshold (${threshold}).
          Please top up your account to avoid service interruptions.
        `;

        // Add the alert to the page
        const container = document.querySelector('.container');
        if (container) {
          container.prepend(alertDiv);
        }
      }
    }
  } catch (error) {
    console.error('Balance monitoring failed:', error);
  }
}

// Example usage
document.addEventListener('DOMContentLoaded', async function() {
  try {
    // Check balance when page loads
    const balanceElement = document.getElementById('current-balance');
    if (balanceElement) {
      const balance = await checkBalance();
      balanceElement.textContent = balance.toFixed(2);
    }

    // Monitor balance with a threshold of 200
    monitorBalance(200);

    // Setup periodic balance checking (every 30 minutes)
    setInterval(() => monitorBalance(200), 30 * 60 * 1000);
  } catch (error) {
    console.error('Error in balance operations:', error);
  }
});

API Docs