/api/program/list-serial-numbers

GET

Returns 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.

šŸ’” Use Cases

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
āš ļø Scanned Folders

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.

šŸ“Œ 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

status string
Always "success" for successful requests.
operation string
Always "list-serial-numbers".
wallet string
Name of the active wallet that was scanned.
coins array
Array of coin objects. Each object contains:
serial_number integer
Unique serial number of the coin (0 to 16,777,216).
denomination integer
Denomination code (-8 to +11). See denomination table below.
folder string
Current location: "Bank" (authenticated) or "Fracked" (partially authenticated).
total_coins integer
Total number of coins found across both folders.
šŸ“Š Denomination Codes

CloudCoin uses binary encoding for denominations:

Code Value Code Value
-80.000000013100
-70.00000014250
-10.151,000
0165,000
15725,000
225101,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

šŸ“ Example 1: Duplicate Detection Across Wallets

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');
    }
}
šŸ“ Example 2: Coin Tracking Dashboard

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.