Account Balance

Endpoint

The account balance endpoint supports both GET and POST HTTP methods. Both methods behave identically and return the same response structure. This dual-method support exists for convenience: some HTTP client libraries and proxy configurations handle GET requests differently from POST requests, so supporting both methods ensures you can always retrieve your balance regardless of your infrastructure constraints.

Authentication

All requests to the BBRE API require authentication via an API key. You must include your API key in the HTTP headers of every request, including balance queries. The API accepts the key through either the x-api-key header or the apikey header. Both header names are supported and functionally identical. If no API key is provided, the API returns a 401 error with the API_KEY_REQUIRED error code. If the provided key is invalid or belongs to a suspended or inactive account, the API returns a 403 error with the appropriate error code (INVALID_API_KEY, ACCOUNT_SUSPENDED, or ACCOUNT_INACTIVE).

Unlike most other BBRE endpoints, the balance endpoint does not require a Content-Type header when using the GET method because there is no request body. If you use the POST method, you can optionally include Content-Type: application/json but it is not required since the endpoint ignores the request body entirely.

Request Parameters

The account balance endpoint does not accept any request parameters. There is no request body, no query parameters, and no URL parameters. The only requirement is a valid API key in the request headers. This makes the balance endpoint the simplest endpoint in the BBRE API to call. When using the GET method, simply send a GET request with your API key header. When using the POST method, you can send an empty body or no body at all. The endpoint identifies your account entirely through the API key and returns the balance associated with that account.

Response Format

The balance endpoint returns a JSON response containing your current account balance. On success, the response includes the standard BBRE success fields plus the balance value as a floating-point number. The balance represents your available credit in USD and reflects all charges processed up to the moment of the request.

Success Response (200)

A successful balance query returns the following structure. The balance field is a floating-point number representing your current credit. A balance of 0 means you have no remaining credit and any charged API operations will fail until you add funds. The service field always contains "MyDisct Solver BBRE" to identify which service processed the request.

{
  "success": true,
  "service": "MyDisct Solver BBRE",
  "balance": 125.50
}

Error Response Examples

When the balance query fails, the API returns an error response with the appropriate HTTP status code, error code, and a descriptive message. The most common error scenarios for this endpoint are authentication-related, since the endpoint itself has no parameters that could be invalid.

401 - API Key Required

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "API_KEY_REQUIRED",
    "message": "API key is required. Please provide your API key in the x-api-key or apikey header."
  }
}

403 - Invalid API Key

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided API key is invalid or does not exist."
  }
}

403 - Account Suspended

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "ACCOUNT_SUSPENDED",
    "message": "Your account has been suspended. Please contact support for more information."
  }
}

500 - Service Error

{
  "success": false,
  "service": "MyDisct Solver BBRE",
  "error": {
    "code": "SERVICE_ERROR",
    "message": "An internal server error occurred. Please try again later."
  }
}

Code Examples

The following examples demonstrate how to check your account balance using different programming languages and HTTP methods. Since the balance endpoint supports both GET and POST, examples are provided for both methods. All examples show complete, working code that you can copy and run directly. Remember to replace YOUR_API_KEY with your actual BBRE API key.

GET Request with JavaScript (fetch)

The simplest way to check your balance using the native fetch API. Since this is a GET request with no body, you only need to include the authentication header.

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";

async function checkBalance() {
  const response = await fetch(API_BASE + "/account/balance", {
    method: "GET",
    headers: {
      "x-api-key": API_KEY
    }
  });

  const data = await response.json();

  if (data.success) {
    console.log("Current balance: $" + data.balance.toFixed(2));
  } else {
    console.log("Error:", data.error.code, data.error.message);
  }

  return data.balance;
}

checkBalance();

POST Request with JavaScript (fetch)

If your application already uses POST for all BBRE API calls, you can use POST for the balance endpoint as well. The response is identical to the GET method.

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";

async function checkBalancePost() {
  const response = await fetch(API_BASE + "/account/balance", {
    method: "POST",
    headers: {
      "x-api-key": API_KEY
    }
  });

  const data = await response.json();
  console.log("Current balance: $" + data.balance.toFixed(2));
  return data.balance;
}

checkBalancePost();

Python (requests library)

Checking your balance with Python using the popular requests library. The example shows both GET and POST approaches.

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "x-api-key": API_KEY
}

response = requests.get(
    API_BASE + "/account/balance",
    headers=headers
)

data = response.json()

if data["success"]:
    print(f"Current balance: ${data['balance']:.2f}")
else:
    print(f"Error: {data['error']['code']}")

import requests

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "x-api-key": API_KEY
}

response = requests.post(
    API_BASE + "/account/balance",
    headers=headers
)

data = response.json()
print(f"Current balance: ${data['balance']:.2f}")

cURL

Quick balance checks from the command line using cURL. The GET method is the natural choice for cURL since it requires no body.

curl https://bbre-solver-api.mydisct.com/account/balance \
  -H "x-api-key: YOUR_API_KEY"

curl -X POST https://bbre-solver-api.mydisct.com/account/balance \
  -H "x-api-key: YOUR_API_KEY"

Balance Monitoring Patterns

In production systems, you rarely call the balance endpoint in isolation. Instead, you integrate balance checks into your application workflow to prevent failed requests due to insufficient funds and to trigger alerts when your balance drops below a threshold. The following patterns demonstrate common approaches to balance monitoring that you can adapt to your specific use case.

Pre-Flight Balance Check

Before submitting a batch of requests or creating an expensive session, check your balance to ensure you have sufficient funds. This prevents wasted time and partial batch failures where some requests succeed and others fail mid-batch due to balance depletion. The pre-flight check is especially important when you are about to submit a large number of requests in a loop, because each failed request still consumes network round-trip time even though it returns an error immediately.

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const authHeaders = {
  "Content-Type": "application/json",
  "x-api-key": API_KEY
};

async function getBalance() {
  const response = await fetch(API_BASE + "/account/balance", {
    headers: { "x-api-key": API_KEY }
  });
  const data = await response.json();
  return data.balance;
}

async function submitBatchWithBalanceCheck(urls) {
  const balance = await getBalance();
  const estimatedCost = urls.length * 0.01;

  if (balance < estimatedCost) {
    console.log("Insufficient balance for batch.");
    console.log("Current: $" + balance.toFixed(2));
    console.log("Estimated cost: $" + estimatedCost.toFixed(2));
    return;
  }

  console.log("Balance sufficient. Submitting " + urls.length + " requests...");

  for (const url of urls) {
    const response = await fetch(API_BASE + "/request/execute", {
      method: "POST",
      headers: authHeaders,
      body: JSON.stringify({ url: url, method: "GET" })
    });
    const result = await response.json();
    console.log(url + " -> " + result.success);
  }
}

submitBatchWithBalanceCheck([
  "https://example.com/page1",
  "https://example.com/page2",
  "https://example.com/page3"
]);

Low Balance Alert System

Set up a periodic balance check that triggers an alert when your balance drops below a configurable threshold. This gives you time to add funds before your balance reaches zero and your production workflows start failing. The alert threshold should be set high enough to cover at least a few hours of normal usage, giving you a comfortable window to respond.

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";
const LOW_BALANCE_THRESHOLD = 5.00;
const CHECK_INTERVAL_MS = 60000;

async function checkBalanceAndAlert() {
  try {
    const response = await fetch(API_BASE + "/account/balance", {
      headers: { "x-api-key": API_KEY }
    });
    const data = await response.json();

    if (data.success && data.balance < LOW_BALANCE_THRESHOLD) {
      console.log("[ALERT] Low balance: $" + data.balance.toFixed(2));
      console.log("Threshold: $" + LOW_BALANCE_THRESHOLD.toFixed(2));
      await sendAlertNotification(data.balance);
    }
  } catch (error) {
    console.log("Balance check failed:", error.message);
  }
}

async function sendAlertNotification(balance) {
  console.log("Sending low balance notification: $" + balance.toFixed(2));
}

setInterval(checkBalanceAndAlert, CHECK_INTERVAL_MS);
checkBalanceAndAlert();

Balance Check with Python

A Python implementation of the pre-flight balance check pattern. This is useful when your BBRE integration is built in Python and you want to verify funds before starting a scraping or automation workflow.

import requests
import time

API_BASE = "https://bbre-solver-api.mydisct.com"
API_KEY = "YOUR_API_KEY"

headers = {
    "x-api-key": API_KEY
}

def get_balance():
    response = requests.get(
        API_BASE + "/account/balance",
        headers=headers
    )
    data = response.json()
    if data["success"]:
        return data["balance"]
    raise Exception(data["error"]["message"])

def check_balance_before_batch(url_list, cost_per_request=0.01):
    balance = get_balance()
    total_cost = len(url_list) * cost_per_request

    if balance < total_cost:
        print(f"Insufficient balance: ${balance:.2f}")
        print(f"Required: ${total_cost:.2f} for {len(url_list)} requests")
        return False

    print(f"Balance OK: ${balance:.2f} (need ${total_cost:.2f})")
    return True

urls = [
    "https://example.com/page1",
    "https://example.com/page2",
    "https://example.com/page3"
]

if check_balance_before_batch(urls):
    print("Proceeding with batch...")

Node.js SDK Usage

The mydisctsolver-bbre Node.js SDK provides a convenient getBalance() method on the BBREClient class that wraps the GET /account/balance endpoint. The SDK handles authentication headers and response parsing automatically, returning the balance value directly as a number instead of the full response object. This makes balance checks a single line of code in your application.

Basic Balance Check

const { BBREClient } = require("mydisctsolver-bbre");

const client = new BBREClient({ apiKey: "YOUR_API_KEY" });

async function checkBalance() {
  const balance = await client.getBalance();
  console.log("Current balance: $" + balance.toFixed(2));
  return balance;
}

checkBalance();

SDK Balance Check Before Operations

Combine the SDK getBalance() method with other SDK operations to implement a pre-flight balance check pattern. The SDK returns the balance as a plain number, so you can compare it directly against your threshold without parsing the response.

const { BBREClient } = require("mydisctsolver-bbre");

const client = new BBREClient({
  apiKey: "YOUR_API_KEY",
  mode: "passive",
  sensibility: "medium"
});

async function safeRequest(url) {
  const balance = await client.getBalance();

  if (balance < 0.01) {
    throw new Error("Balance too low: $" + balance.toFixed(2));
  }

  const result = await client.request({
    url: url,
    method: "GET"
  });

  console.log("Request completed. Status:", result.statusCode);
  return result;
}

safeRequest("https://example.com");

SDK Balance Monitoring Loop

Use the SDK to build a simple balance monitoring loop that logs your balance at regular intervals. This is useful during development and testing to track how quickly your balance is being consumed by your workflow.

const { BBREClient } = require("mydisctsolver-bbre");

const client = new BBREClient({ apiKey: "YOUR_API_KEY" });

async function monitorBalance(intervalMs, thresholdUsd) {
  const check = async () => {
    try {
      const balance = await client.getBalance();
      const timestamp = new Date().toISOString();
      console.log("[" + timestamp + "] Balance: $" + balance.toFixed(2));

      if (balance < thresholdUsd) {
        console.log("[WARNING] Balance below threshold of $" + thresholdUsd.toFixed(2));
      }
    } catch (error) {
      console.log("Balance check error:", error.message);
    }
  };

  await check();
  setInterval(check, intervalMs);
}

monitorBalance(30000, 10.00);

The SDK getBalance() method internally sends a GET request to /account/balance and extracts the balance field from the response. If the request fails, the method throws an error with the error message from the API response. For more details on the SDK, see the Node.js SDK Overview and the Account Methods documentation.

Error Codes

The following table lists all error codes that can be returned by the account balance endpoint, along with their HTTP status codes, descriptions, and recommended solutions. Because the balance endpoint has no request parameters, the only errors you will encounter are authentication-related errors and server-side errors. Implementing proper error handling for these codes ensures your balance monitoring logic degrades gracefully when issues occur.

Error Handling Example

The following example demonstrates robust error handling for the balance endpoint. In production systems, your balance check should never crash your application. Instead, handle each error code appropriately and fall back to a safe default behavior when the balance cannot be determined.

const API_BASE = "https://bbre-solver-api.mydisct.com";
const API_KEY = "YOUR_API_KEY";

async function getBalanceSafe() {
  try {
    const response = await fetch(API_BASE + "/account/balance", {
      headers: { "x-api-key": API_KEY }
    });

    const data = await response.json();

    if (data.success) {
      return { balance: data.balance, error: null };
    }

    const errorCode = data.error.code;

    if (errorCode === "API_KEY_REQUIRED" || errorCode === "INVALID_API_KEY") {
      return { balance: null, error: "Authentication failed: " + errorCode };
    }

    if (errorCode === "ACCOUNT_SUSPENDED" || errorCode === "ACCOUNT_INACTIVE") {
      return { balance: null, error: "Account issue: " + errorCode };
    }

    return { balance: null, error: "Unexpected error: " + errorCode };

  } catch (networkError) {
    return { balance: null, error: "Network error: " + networkError.message };
  }
}

async function main() {
  const result = await getBalanceSafe();

  if (result.error) {
    console.log("Could not check balance:", result.error);
    return;
  }

  console.log("Balance: $" + result.balance.toFixed(2));
}

main();

Best Practices

Common Issues

Issue 1: Balance Shows Zero But Funds Were Added Recently

Solution: Balance updates from the dashboard are processed in real time, but there can be a brief delay of a few seconds between the payment confirmation and the balance update in the database. Wait 10-15 seconds after adding funds and then check your balance again. If the balance still does not reflect your payment after a minute, verify that the payment was completed successfully in your dashboard transaction history. If the payment shows as completed but the balance is not updated, contact MyDisct Solver support with your transaction ID.

Issue 2: Balance Decreases Faster Than Expected

Solution: Different BBRE operations have different costs. Session creation, adaptive mode requests, and high sensibility requests typically cost more than simple passive mode requests with low sensibility. Check the Usage History endpoint to see the exact charge for each operation. Also verify that you do not have other applications or scripts using the same API key, which would consume balance from the same account. If you are using sessions, remember that session creation itself may have an associated cost in addition to the per-request charges within the session.

Issue 3: Getting 401 Error When Checking Balance

Solution: The most common cause is using the wrong header name. The BBRE API accepts the API key through the x-api-key or apikey HTTP headers only. It does not support API key authentication through query parameters, URL paths, or the Authorization header. Verify that your HTTP client is sending the header with the exact name x-api-key (all lowercase with hyphens) or apikey (all lowercase, no hyphens). Also check that your API key value does not contain leading or trailing whitespace, which can happen when copying from the dashboard. Some HTTP client libraries automatically trim header values, but others do not.

Related Documentation

• Account Info - Retrieve detailed account information including your username, email, status, balance, and usage statistics such as total requests, success rate, and active session count
• Usage History - View your complete request history with per-request cost breakdowns, processing times, and status information to understand exactly how your balance is being consumed
• Account Sessions - List all your sessions with filtering options to manage active sessions and understand session-related charges
• Create Request - Submit asynchronous BBRE requests that deduct from your balance upon completion
• Execute Request - Submit synchronous BBRE requests for immediate results, with balance deduction on completion
• Create Session - Create BBRE sessions that may have an associated creation cost deducted from your balance
• SDK Account Methods - Learn about the getBalance() and getAccountInfo() methods in the Node.js SDK
• BBRE Engine Overview - Understand the BBRE architecture, operating modes, and how different configurations affect pricing