/api/wallets/balance
GETReturns 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.
Bank: Authenticated coins (13+ RAIDA passes)
Fracked: Partially authenticated coins (some RAIDA failures)
Limbo: Coins in uncertain status
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.
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
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
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.