/api/wallets/balance

GET

Returns the balance and coin counts for a specified wallet, broken down by folder.

Description

The `/api/wallets/balance` endpoint gets the balance and coin counts for a specified wallet path. It scans the wallet's Bank, Fracked, and Limbo folders to calculate the total value and coin counts. It also verifies the balance against the recorded transaction history to check for discrepancies.

💡 Folder Organization

Bank: Authenticated coins (13+ RAIDA passes)
Fracked: Partially authenticated coins (some RAIDA failures)
Limbo: Coins in uncertain status

📊 Balance Reconciliation

The `balance_reconciled` flag indicates whether the current wallet balance matches the last recorded balance in the transaction history. A mismatch may indicate coins were added/removed manually.

🔢 Max Coins Limit (Optional)

If configured in program-config.txt with max_coins_allowed set to a value greater than 0, the response will include two additional fields:

  • max_coins_allowed: The configured maximum number of coins allowed in the wallet
  • exceeds_limit: True if the total coin count exceeds the configured limit

This limit is enforced by the frontend application. The backend simply reports the limit and whether it's been exceeded.

Parameters

wallet_path
string (query)
Required
The file system path to the wallet directory to get balance for (e.g., E:\Data\Wallets\Default on Windows or /home/user/CloudCoin/Wallets/MyWallet on Linux/macOS).

Response

Returns a JSON object containing balance information for the specified wallet.

Response Properties

command string
Always "wallet-balance".
success boolean
Always true if the request was processed.
wallet_path string
The full filesystem path to the wallet directory.
wallet_name string
The wallet's display name (extracted from path).
total_coins integer
Total number of coins across all folders.
total_value number
Total value of all coins (may include fractional amounts).
folders object
Breakdown of coins and values by folder.
folders.bank_coins integer
Number of coins in the Bank folder.
folders.bank_value number
Total value of coins in the Bank folder.
folders.fracked_coins integer
Number of coins in the Fracked folder.
folders.fracked_value number
Total value of coins in the Fracked folder.
folders.limbo_coins integer
Number of coins in the Limbo folder.
folders.limbo_value number
Total value of coins in the Limbo folder.
balance_reconciled boolean
True if the current balance matches the last recorded balance in transaction history.
recorded_balance number
The last recorded balance from the transaction history.
max_coins_allowed integer
Maximum number of coins allowed in the wallet (optional - only present if configured in program-config.txt with a value > 0).
exceeds_limit boolean
True if total_coins exceeds max_coins_allowed (optional - only present if max_coins_allowed is configured).

Example Response (Success)

{
  "command": "wallet-balance",
  "success": true,
  "wallet_path": "E:\\Data\\Wallets\\Default",
  "wallet_name": "Default",
  "total_coins": 0,
  "total_value": 0,
  "folders": {
    "bank_coins": 0,
    "bank_value": 0,
    "fracked_coins": 0,
    "fracked_value": 0,
    "limbo_coins": 0,
    "limbo_value": 0
  },
  "balance_reconciled": true,
  "recorded_balance": 0
}

Example Response (Unreconciled Balance)

{
  "command": "wallet-balance",
  "success": true,
  "wallet_path": "E:\\Data\\Wallets\\Default",
  "wallet_name": "Default",
  "total_coins": 130,
  "total_value": 13000.0,
  "folders": {
    "bank_coins": 125,
    "bank_value": 12750.0,
    "fracked_coins": 5,
    "fracked_value": 250.0,
    "limbo_coins": 0,
    "limbo_value": 0.0
  },
  "balance_reconciled": false,
  "recorded_balance": 12750.0
}

Example Error Response (No Wallet)

{
  "error": "No active wallet"
}

Examples

JavaScript (fetch)

const API_HOST = 'http://localhost:8080';

// Get balance for a specific wallet path
async function getWalletBalance(walletPath) {
    try {
        const encodedPath = encodeURIComponent(walletPath);
        const response = await fetch(`${API_HOST}/api/wallets/balance?wallet_path=${encodedPath}`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log(`Wallet: ${result.wallet}`);
            console.log(`Total Value: ${result.total_value}`);
            console.log(`Total Coins: ${result.total_coins}`);
            console.log('\nBreakdown:');
            console.log(`  Bank: ${result.folders.bank_coins} coins, ${result.folders.bank_value} value`);
            console.log(`  Fracked: ${result.folders.fracked_coins} coins, ${result.folders.fracked_value} value`);
            console.log(`  Limbo: ${result.folders.limbo_coins} coins, ${result.folders.limbo_value} value`);

            if (!result.balance_reconciled) {
                console.warn(`Warning: Balance mismatch! Current: ${result.total_value}, Recorded: ${result.recorded_balance}`);
            }
        } else {
            console.error('Failed to get balance:', result.error);
        }
    } catch (error) {
        console.error('Error getting balance:', error);
    }
}

// Usage - Windows
getWalletBalance('E:\\Data\\Wallets\\Default');

// Usage - Linux/macOS
// getWalletBalance('/home/user/CloudCoin/Wallets/Default');

cURL

# Get balance for a wallet - Windows
curl -X GET "http://localhost:8080/api/wallets/balance?wallet_path=E:\Data\Wallets\Default"

# Linux/macOS
# curl -X GET "http://localhost:8080/api/wallets/balance?wallet_path=/home/user/CloudCoin/Wallets/Default"

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

const ApiHost = "http://localhost:8080"

type FolderBreakdown struct {
    BankCoins    int     `json:"bank_coins"`
    BankValue    float64 `json:"bank_value"`
    FrackedCoins int     `json:"fracked_coins"`
    FrackedValue float64 `json:"fracked_value"`
    LimboCoins   int     `json:"limbo_coins"`
    LimboValue   float64 `json:"limbo_value"`
}

type BalanceResponse struct {
    Status            string          `json:"status"`
    Operation         string          `json:"operation"`
    Wallet            string          `json:"wallet"`
    TotalCoins        int             `json:"total_coins"`
    TotalValue        float64         `json:"total_value"`
    Folders           FolderBreakdown `json:"folders"`
    BalanceReconciled bool            `json:"balance_reconciled"`
    RecordedBalance   float64         `json:"recorded_balance"`
}

func getWalletBalance(walletPath string) {
    // Build URL with wallet_path parameter
    endpoint := fmt.Sprintf("%s/api/wallets/balance?wallet_path=%s",
        ApiHost, url.QueryEscape(walletPath))

    resp, err := http.Get(endpoint)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := ioutil.ReadAll(resp.Body)

    var result BalanceResponse
    if err := json.Unmarshal(body, &result); err != nil {
        panic(err)
    }

    fmt.Printf("Wallet: %s\n", result.Wallet)
    fmt.Printf("Total Value: %.2f\n", result.TotalValue)
    fmt.Printf("Total Coins: %d\n", result.TotalCoins)
    fmt.Println("\nBreakdown:")
    fmt.Printf("  Bank: %d coins, %.2f value\n", result.Folders.BankCoins, result.Folders.BankValue)
    fmt.Printf("  Fracked: %d coins, %.2f value\n", result.Folders.FrackedCoins, result.Folders.FrackedValue)
    fmt.Printf("  Limbo: %d coins, %.2f value\n", result.Folders.LimboCoins, result.Folders.LimboValue)

    if !result.BalanceReconciled {
        fmt.Printf("\nWarning: Balance mismatch! Current: %.2f, Recorded: %.2f\n",
            result.TotalValue, result.RecordedBalance)
    }
}

func main() {
    // Get balance for a wallet - Windows
    getWalletBalance("E:\\Data\\Wallets\\Default")

    // Linux/macOS
    // getWalletBalance("/home/user/CloudCoin/Wallets/Default")
}

Related Endpoints

/api/coins/import

Import coins into your wallet from the Import folder to increase your balance.

/api/wallet/list

View all configured wallets to see which wallet's balance is being displayed.