/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)
Optional
The file system path to the wallet directory to get balance for. If omitted, the API uses the Default wallet relative to the executable.

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_notes integer
Total number of note files across Bank, Fracked, and Limbo.
total_value number
Total value of all coins (may include fractional amounts).
bank_notes integer
Number of notes in the Bank folder.
bank_value number
Total value of notes in the Bank folder.
fracked_notes integer
Number of notes in the Fracked folder.
fracked_value number
Total value of notes in the Fracked folder.
limbo_notes integer
Number of notes in the Limbo folder.
limbo_value number
Total value of notes in the Limbo folder.
balance_reconciled boolean
True if the current balance matches the last recorded balance in transaction history.
log_balance number
Balance from the transaction log after reconciliation handling.

Example Response (Success)

{
  "command": "wallet-balance",
  "success": true,
  "wallet_path": "E:/Client_Data/Wallets/Default",
  "wallet_name": "Default",
  "total_notes": 0,
  "total_value": 0,
  "bank_notes": 0,
  "bank_value": 0,
  "fracked_notes": 0,
  "fracked_value": 0,
  "limbo_notes": 0,
  "limbo_value": 0,
  "balance_reconciled": true,
  "log_balance": 0
}

Example Response (Unreconciled Balance)

{
  "command": "wallet-balance",
  "success": true,
  "wallet_path": "E:/Client_Data/Wallets/Default",
  "wallet_name": "Default",
  "total_notes": 130,
  "total_value": 13000.0,
  "bank_notes": 125,
  "bank_value": 12750.0,
  "fracked_notes": 5,
  "fracked_value": 250.0,
  "limbo_notes": 0,
  "limbo_value": 0.0,
  "balance_reconciled": false,
  "log_balance": 12750.0,
  "adjustment_made": true,
  "adjustment_amount": 250.0
}

Example Error Response (No Wallet)

{
  "error": true,
  "message": "Wallet not found",
  "code": 404
}

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.success) {
            console.log(`Wallet: ${result.wallet_name}`);
            console.log(`Total Value: ${result.total_value}`);
            console.log(`Total Notes: ${result.total_notes}`);
            console.log('\nBreakdown:');
            console.log(`  Bank: ${result.bank_notes} notes, ${result.bank_value} value`);
            console.log(`  Fracked: ${result.fracked_notes} notes, ${result.fracked_value} value`);
            console.log(`  Limbo: ${result.limbo_notes} notes, ${result.limbo_value} value`);

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

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

// Usage - Linux/macOS
// getWalletBalance('E:/Client_Data/Wallets/Default');

cURL

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

# Linux/macOS
# curl -X GET "http://localhost:8080/api/wallets/balance?wallet_path=E:/Client_Data/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:/Client_Data/Wallets/Default")

    // Linux/macOS
    // getWalletBalance("E:/Client_Data/Wallets/Default")
}

Related Endpoints

/api/coins/import

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

/api/wallets/list

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