/api/program/list-serial-numbers
GETReturns a complete inventory of all coin serial numbers in the active wallet with their denominations and locations.
Description
The /api/program/list-serial-numbers endpoint provides a comprehensive inventory of all CloudCoin serial numbers stored in the active wallet's Bank and Fracked folders. Each coin entry includes its serial number, denomination value, and current folder location.
This endpoint is particularly useful for tracking coins, detecting duplicates, performing audits, and maintaining accurate records of wallet holdings. Only coins in the Bank (fully authenticated, 13+ RAIDA passes) and Fracked (partially authenticated, <13 RAIDA passes) folders are included in the listing.
This endpoint is perfect for:
- Wallet Inventory: Get a complete list of all coins in your wallet
- Duplicate Detection: Identify coins with the same serial number across multiple wallets
- Coin Tracking: Monitor specific serial numbers through transactions
- Audit Trails: Maintain records for compliance and accounting
- Reporting: Generate detailed coin holdings reports
- Troubleshooting: Verify coin presence and location during debugging
This endpoint only scans coins in the Bank and Fracked folders. Coins in other folders (Import, Export, Suspect, Counterfeit, Limbo, etc.) are not included in the results.
Parameters
This endpoint does not require any parameters. It automatically uses the currently active wallet.
To check which wallet is currently active, use the /api/program/status endpoint. To switch wallets, use the /api/wallet/switch endpoint.
Response
Returns a JSON object with a complete list of coins and a summary count.
Response Properties
CloudCoin uses binary encoding for denominations:
| Code | Value | Code | Value |
|---|---|---|---|
| -8 | 0.00000001 | 3 | 100 |
| -7 | 0.0000001 | 4 | 250 |
| -1 | 0.1 | 5 | 1,000 |
| 0 | 1 | 6 | 5,000 |
| 1 | 5 | 7 | 25,000 |
| 2 | 25 | 10 | 1,000,000 |
Note: Code 11 is reserved for special purposes (Keys/NFTs).
Example Response
{
"status": "success",
"operation": "list-serial-numbers",
"wallet": "Default",
"coins": [
{
"serial_number": 1234567,
"denomination": 4,
"folder": "Bank"
},
{
"serial_number": 7654321,
"denomination": 3,
"folder": "Bank"
},
{
"serial_number": 9876543,
"denomination": 2,
"folder": "Fracked"
},
{
"serial_number": 5555555,
"denomination": 5,
"folder": "Bank"
}
],
"total_coins": 4
}
In this example:
- Coin #1234567 (denomination 4 = 250cc) in Bank folder
- Coin #7654321 (denomination 3 = 100cc) in Bank folder
- Coin #9876543 (denomination 2 = 25cc) in Fracked folder
- Coin #5555555 (denomination 5 = 1,000cc) in Bank folder
- Total: 4 coins worth 1,375cc
Error Responses
The endpoint may return the following error conditions:
No Active Wallet
Returns when no wallet is currently selected.
{
"status": "error",
"operation": "list-serial-numbers",
"message": "No active wallet",
"error_code": 500
}
Examples
JavaScript (fetch)
const API_HOST = 'http://localhost:8080';
// Denomination code to value mapping
const DENOMINATION_MAP = {
'-8': 0.00000001, '-7': 0.0000001, '-1': 0.1,
'0': 1, '1': 5, '2': 25, '3': 100, '4': 250, '5': 1000,
'6': 5000, '7': 25000, '8': 100000, '9': 250000, '10': 1000000,
'11': 'Special'
};
async function listSerialNumbers() {
try {
const response = await fetch(`${API_HOST}/api/program/list-serial-numbers`);
const result = await response.json();
if (result.status === 'error') {
console.error('Error:', result.message);
return;
}
console.log(`Wallet: ${result.wallet}`);
console.log(`Total Coins: ${result.total_coins}\n`);
// Group by folder
const byFolder = result.coins.reduce((acc, coin) => {
if (!acc[coin.folder]) acc[coin.folder] = [];
acc[coin.folder].push(coin);
return acc;
}, {});
// Display coins by folder
for (const [folder, coins] of Object.entries(byFolder)) {
console.log(`\n${folder} (${coins.length} coins):`);
coins.forEach(coin => {
const value = DENOMINATION_MAP[coin.denomination];
console.log(` SN ${coin.serial_number} - ${value}cc`);
});
}
// Calculate total value
const totalValue = result.coins.reduce((sum, coin) => {
const value = DENOMINATION_MAP[coin.denomination];
return sum + (typeof value === 'number' ? value : 0);
}, 0);
console.log(`\nTotal Value: ${totalValue}cc`);
} catch (error) {
console.error('Error fetching serial numbers:', error);
}
}
listSerialNumbers();
cURL
# Get list of serial numbers
curl -X GET "http://localhost:8080/api/program/list-serial-numbers"
# Pretty print with jq
curl -X GET "http://localhost:8080/api/program/list-serial-numbers" | jq '.'
# Get only coins in Bank folder
curl -X GET "http://localhost:8080/api/program/list-serial-numbers" \
| jq '.coins[] | select(.folder == "Bank")'
# Count coins by folder
curl -X GET "http://localhost:8080/api/program/list-serial-numbers" \
| jq '.coins | group_by(.folder) | map({folder: .[0].folder, count: length})'
# Find specific serial number
curl -X GET "http://localhost:8080/api/program/list-serial-numbers" \
| jq '.coins[] | select(.serial_number == 1234567)'
Go
package main
import (
"encoding/json"
"fmt"
"io/ioutil"
"net/http"
)
const ApiHost = "http://localhost:8080"
type Coin struct {
SerialNumber int `json:"serial_number"`
Denomination int `json:"denomination"`
Folder string `json:"folder"`
}
type ListResponse struct {
Status string `json:"status"`
Operation string `json:"operation"`
Wallet string `json:"wallet"`
Coins []Coin `json:"coins"`
TotalCoins int `json:"total_coins"`
}
// Denomination code to value mapping
var denominationValues = map[int]float64{
-8: 0.00000001, -7: 0.0000001, -1: 0.1,
0: 1, 1: 5, 2: 25, 3: 100, 4: 250, 5: 1000,
6: 5000, 7: 25000, 8: 100000, 9: 250000, 10: 1000000,
}
func main() {
resp, err := http.Get(fmt.Sprintf("%s/api/program/list-serial-numbers", ApiHost))
if err != nil {
panic(err)
}
defer resp.Body.Close()
body, _ := ioutil.ReadAll(resp.Body)
var result ListResponse
if err := json.Unmarshal(body, &result); err != nil {
panic(err)
}
if result.Status == "error" {
fmt.Println("Error:", result.Operation)
return
}
fmt.Printf("Wallet: %s\n", result.Wallet)
fmt.Printf("Total Coins: %d\n\n", result.TotalCoins)
// Group by folder
byFolder := make(map[string][]Coin)
for _, coin := range result.Coins {
byFolder[coin.Folder] = append(byFolder[coin.Folder], coin)
}
// Display coins by folder
for folder, coins := range byFolder {
fmt.Printf("%s (%d coins):\n", folder, len(coins))
for _, coin := range coins {
value := denominationValues[coin.Denomination]
fmt.Printf(" SN %d - %.2fcc\n", coin.SerialNumber, value)
}
fmt.Println()
}
// Calculate total value
var totalValue float64
for _, coin := range result.Coins {
if val, ok := denominationValues[coin.Denomination]; ok {
totalValue += val
}
}
fmt.Printf("Total Value: %.2fcc\n", totalValue)
}
Python
import requests
from collections import defaultdict
API_HOST = "http://localhost:8080"
# Denomination code to value mapping
DENOMINATION_MAP = {
-8: 0.00000001, -7: 0.0000001, -1: 0.1,
0: 1, 1: 5, 2: 25, 3: 100, 4: 250, 5: 1000,
6: 5000, 7: 25000, 8: 100000, 9: 250000, 10: 1000000,
11: 'Special'
}
def list_serial_numbers():
try:
response = requests.get(f"{API_HOST}/api/program/list-serial-numbers")
result = response.json()
if result['status'] == 'error':
print(f"Error: {result['message']}")
return
print(f"Wallet: {result['wallet']}")
print(f"Total Coins: {result['total_coins']}\n")
# Group by folder
by_folder = defaultdict(list)
for coin in result['coins']:
by_folder[coin['folder']].append(coin)
# Display coins by folder
for folder, coins in by_folder.items():
print(f"\n{folder} ({len(coins)} coins):")
for coin in coins:
value = DENOMINATION_MAP[coin['denomination']]
print(f" SN {coin['serial_number']} - {value}cc")
# Calculate total value
total_value = sum(
DENOMINATION_MAP[coin['denomination']]
for coin in result['coins']
if isinstance(DENOMINATION_MAP[coin['denomination']], (int, float))
)
print(f"\nTotal Value: {total_value}cc")
# Find duplicates
serial_counts = defaultdict(int)
for coin in result['coins']:
serial_counts[coin['serial_number']] += 1
duplicates = {sn: count for sn, count in serial_counts.items() if count > 1}
if duplicates:
print("\nā ļø Duplicate Serial Numbers:")
for sn, count in duplicates.items():
print(f" SN {sn} appears {count} times")
except requests.RequestException as e:
print(f"Error fetching serial numbers: {e}")
if __name__ == "__main__":
list_serial_numbers()
Use Case Examples
When managing multiple wallets, it's important to detect if the same coin serial number exists in different wallets (which would indicate counterfeit coins or synchronization issues).
async function detectDuplicatesAcrossWallets() {
const wallets = ['Wallet1', 'Wallet2', 'Wallet3'];
const allSerials = new Map(); // serial_number -> [wallet_names]
for (const wallet of wallets) {
// Switch to wallet
await fetch(`${API_HOST}/api/wallet/switch`, {
method: 'POST',
headers: { 'Content-Type': 'application/json' },
body: JSON.stringify({ wallet_name: wallet })
});
// Get serial numbers
const response = await fetch(`${API_HOST}/api/program/list-serial-numbers`);
const result = await response.json();
result.coins.forEach(coin => {
if (!allSerials.has(coin.serial_number)) {
allSerials.set(coin.serial_number, []);
}
allSerials.get(coin.serial_number).push(wallet);
});
}
// Find duplicates
const duplicates = [];
allSerials.forEach((wallets, serial) => {
if (wallets.length > 1) {
duplicates.push({ serial, wallets });
}
});
if (duplicates.length > 0) {
console.log('ā ļø DUPLICATES FOUND:');
duplicates.forEach(dup => {
console.log(` SN ${dup.serial} in: ${dup.wallets.join(', ')}`);
});
} else {
console.log('ā
No duplicates found');
}
}
Create a real-time dashboard showing coin distribution across folders and denomination breakdown.
async function generateCoinDashboard() {
const response = await fetch(`${API_HOST}/api/program/list-serial-numbers`);
const result = await response.json();
// Statistics by folder
const folderStats = result.coins.reduce((acc, coin) => {
if (!acc[coin.folder]) acc[coin.folder] = { count: 0, value: 0 };
acc[coin.folder].count++;
acc[coin.folder].value += DENOMINATION_MAP[coin.denomination] || 0;
return acc;
}, {});
// Statistics by denomination
const denomStats = result.coins.reduce((acc, coin) => {
const value = DENOMINATION_MAP[coin.denomination];
if (!acc[value]) acc[value] = 0;
acc[value]++;
return acc;
}, {});
console.log('=== COIN DASHBOARD ===');
console.log(`\nWallet: ${result.wallet}`);
console.log(`Total Coins: ${result.total_coins}\n`);
console.log('Distribution by Folder:');
Object.entries(folderStats).forEach(([folder, stats]) => {
console.log(` ${folder}: ${stats.count} coins (${stats.value}cc)`);
});
console.log('\nDistribution by Denomination:');
Object.entries(denomStats)
.sort((a, b) => b[0] - a[0])
.forEach(([value, count]) => {
console.log(` ${value}cc: ${count} coins`);
});
}
Related Endpoints
/api/wallet/balance
Get the total balance of the active wallet without detailed coin information.
/api/wallet/show-coins
Display complete coin information including ANs, PANs, and POWN strings.
/api/program/status
Check which wallet is currently active before listing serial numbers.