/api/wallet/show-coins

GET

Returns a detailed list of all coins in a specific wallet folder with metadata including serial numbers, denominations, values, and POWN authentication strings.

Description

The `/api/wallet/show-coins` endpoint scans a specified folder within the active wallet and returns detailed information about every coin file. This endpoint is essential for inventory management, troubleshooting authentication issues, and understanding the health status of individual coins.

Each coin includes its POWN (Proof of Ownership) string, which shows the authentication status across all 25 RAIDA servers. This allows you to identify which specific RAIDAs are failing for fracked coins.

💡 POWN String Explained

The POWN string is a 25-character string where each character represents the authentication status at one RAIDA server:

  • 'p' - Pass (authenticated)
  • 'f' - Fail (counterfeit)
  • 'u' - Untried (not yet tested)
  • 'n' - No reply (timeout)
  • 'e' - Error (RAIDA error)

A coin needs 13 or more 'p' characters to be considered authentic.

💡 Finding Coins That Need Fixing

Use folder=Fracked to identify coins with partial authentication failures. The POWN string will show exactly which RAIDAs failed, making it easier to diagnose network or RAIDA-specific issues.

Parameters

folder string optional

The wallet folder to list coins from. Defaults to "Bank" if not specified.

Valid values: Bank, Fracked, Counterfeit, Import, Export, Grade, Suspect, Pending, Limbo

Default: Bank

📁 Folder Types
  • Bank: Authenticated coins (13+ passes)
  • Fracked: Partially authenticated (some failures but still valid)
  • Counterfeit: Failed authentication (<13 passes)
  • Import: Newly imported coins awaiting processing
  • Export: Coins prepared for export
  • Grade: Coins awaiting grading/sorting
  • Suspect: Coins with uncertain status
  • Pending: Coins being processed
  • Limbo: Coins in uncertain state

Response

Returns a JSON object containing an array of coin objects with detailed metadata.

Response Properties

status string
Always "success" if the request was processed.
operation string
The operation type - "show-coins".
folder string
The folder that was queried.
wallet string
The name of the active wallet (implementation note: returned in C implementation, may not be in all versions).
count integer
Total number of coins in the folder (implementation note: returned as "total_coins" in C implementation).
total_value number
Combined value of all coins in the folder.
coins array
Array of coin objects, each containing detailed metadata.
coins[].serial_number integer
The unique serial number of the coin (1-16777216).
coins[].denomination integer
The denomination code (0=1, 1=5, 2=25, 3=100, 4=250, 5=1000, 6=5000, 7=25000, 8=100000, 9=250000, 10=1000000, 11=Key/NFT).
coins[].value number
The actual value of the coin based on its denomination.
coins[].pown_string string
25-character authentication string showing status at each RAIDA (e.g., "ppppppppppppppppppppppppp" for fully authenticated).
coins[].pass_count integer
Number of RAIDAs that passed authentication (0-25). Note: May not be included in all implementations.
coins[].status string
Authentication status: "authentic" (25 passes), "fracked" (13-24 passes), or "counterfeit" (<13 passes). Note: May not be included in all implementations.

Example Response (Success - Bank Folder)

{
  "status": "success",
  "operation": "show-coins",
  "folder": "Bank",
  "wallet": "Default",
  "total_coins": 3,
  "total_value": 350,
  "coins": [
    {
      "serial_number": 12345,
      "denomination": 3,
      "value": 100,
      "pown_string": "ppppppppppppppppppppppppp"
    },
    {
      "serial_number": 67890,
      "denomination": 4,
      "value": 250,
      "pown_string": "ppppppppppppppppppppppppp"
    }
  ]
}

Example Response (Fracked Folder with Partial Failures)

{
  "status": "success",
  "operation": "show-coins",
  "folder": "Fracked",
  "wallet": "Default",
  "total_coins": 2,
  "total_value": 350,
  "coins": [
    {
      "serial_number": 54321,
      "denomination": 3,
      "value": 100,
      "pown_string": "ppppppppppppfnppppppppppp"
    },
    {
      "serial_number": 98765,
      "denomination": 4,
      "value": 250,
      "pown_string": "pppppppppppppppfppnpppppp"
    }
  ]
}

Example Error Response (No Active Wallet)

{
  "error": "No active wallet set",
  "status_code": 400
}

Example Error Response (Failed to Read Folder)

{
  "error": "Failed to read coins from folder",
  "status_code": 500
}

Examples

JavaScript (fetch)

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

async function showCoins(folder = 'Bank') {
    try {
        const response = await fetch(`${API_HOST}/api/wallet/show-coins?folder=${folder}`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log(`\n=== ${result.folder} Folder ===`);
            console.log(`Wallet: ${result.wallet || 'Unknown'}`);
            console.log(`Total Coins: ${result.total_coins || result.count || 0}`);
            console.log(`Total Value: ${result.total_value}\n`);

            result.coins.forEach((coin, index) => {
                const passCount = (coin.pown_string.match(/p/g) || []).length;
                const failCount = (coin.pown_string.match(/f/g) || []).length;
                const noReplyCount = (coin.pown_string.match(/n/g) || []).length;
                const errorCount = (coin.pown_string.match(/e/g) || []).length;

                console.log(`Coin ${index + 1}:`);
                console.log(`  Serial Number: ${coin.serial_number}`);
                console.log(`  Value: ${coin.value}`);
                console.log(`  POWN: ${coin.pown_string}`);
                console.log(`  Status: ${passCount}/25 Pass, ${failCount}/25 Fail, ${noReplyCount}/25 No Reply, ${errorCount}/25 Error`);
                console.log('');
            });
        } else {
            console.error('Failed to list coins:', result.error);
        }
    } catch (error) {
        console.error('Error listing coins:', error);
    }
}

// Show coins in Bank folder
showCoins('Bank');

// Show coins that need fixing
// showCoins('Fracked');

cURL

# Show coins in Bank folder (default)
curl -X GET "http://localhost:8080/api/wallet/show-coins"

# Show coins in Fracked folder
curl -X GET "http://localhost:8080/api/wallet/show-coins?folder=Fracked"

# Show coins in Import folder
curl -X GET "http://localhost:8080/api/wallet/show-coins?folder=Import"

# Pretty print with jq
curl -X GET "http://localhost:8080/api/wallet/show-coins?folder=Bank" | jq .

Go

package main

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

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

type Coin struct {
    SerialNumber int     `json:"serial_number"`
    Denomination int     `json:"denomination"`
    Value        float64 `json:"value"`
    PownString   string  `json:"pown_string"`
}

type ShowCoinsResponse struct {
    Status     string  `json:"status"`
    Operation  string  `json:"operation"`
    Folder     string  `json:"folder"`
    Wallet     string  `json:"wallet"`
    TotalCoins int     `json:"total_coins"`
    Count      int     `json:"count"`
    TotalValue float64 `json:"total_value"`
    Coins      []Coin  `json:"coins"`
}

func countPownStatus(pownString string) (pass, fail, noReply, errors int) {
    for _, char := range pownString {
        switch char {
        case 'p':
            pass++
        case 'f':
            fail++
        case 'n':
            noReply++
        case 'e':
            errors++
        }
    }
    return
}

func main() {
    folder := "Bank" // or "Fracked", "Import", etc.
    url := fmt.Sprintf("%s/api/wallet/show-coins?folder=%s", ApiHost, folder)

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

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

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

    if result.Status != "success" {
        fmt.Printf("Error: %s\n", string(body))
        return
    }

    totalCoins := result.TotalCoins
    if totalCoins == 0 {
        totalCoins = result.Count
    }

    fmt.Printf("\n=== %s Folder ===\n", result.Folder)
    fmt.Printf("Wallet: %s\n", result.Wallet)
    fmt.Printf("Total Coins: %d\n", totalCoins)
    fmt.Printf("Total Value: %.2f\n\n", result.TotalValue)

    for i, coin := range result.Coins {
        pass, fail, noReply, errors := countPownStatus(coin.PownString)

        fmt.Printf("Coin %d:\n", i+1)
        fmt.Printf("  Serial Number: %d\n", coin.SerialNumber)
        fmt.Printf("  Value: %.2f\n", coin.Value)
        fmt.Printf("  POWN: %s\n", coin.PownString)
        fmt.Printf("  Status: %d/25 Pass, %d/25 Fail, %d/25 No Reply, %d/25 Error\n\n",
            pass, fail, noReply, errors)
    }
}

Understanding POWN Strings

The POWN (Proof of Ownership) string is critical for understanding coin health. Each character position corresponds to a specific RAIDA server (0-24):

Position:  0    5    10   15   20   24
POWN:      ppppppppppppppppppppppppp  (All passes - Authentic)
           ppppppppppppfnppppppppppp  (22 passes - Fracked but valid)
           fffffffffffffffffffffffff  (All fails - Counterfeit)
           ppppppppppppuuuuuuuuuuuuu  (Not fully tested)
🔍 Interpreting POWN Results
  • 25 passes: Perfect coin - all RAIDAs authenticated successfully
  • 13-24 passes: Fracked coin - still valid but should be fixed
  • <13 passes: Counterfeit or lost coin - cannot be recovered
  • Failures in specific positions: Indicates which RAIDA servers are having issues
  • Pattern of 'n' (no reply): Network or connectivity issues
  • Pattern of 'e' (error): RAIDA server errors, may be temporary

Use Cases

1. Inventory Management

// List all authenticated coins
const bankCoins = await showCoins('Bank');
console.log(`You have ${bankCoins.total_coins} coins worth ${bankCoins.total_value}`);

2. Finding Coins to Fix

// Find fracked coins that need repair
const frackedCoins = await showCoins('Fracked');
frackedCoins.coins.forEach(coin => {
    const passCount = (coin.pown_string.match(/p/g) || []).length;
    if (passCount >= 13 && passCount < 25) {
        console.log(`Coin ${coin.serial_number} needs fixing (${passCount}/25 passes)`);
    }
});

3. Troubleshooting RAIDA Issues

// Identify problematic RAIDA servers
const coins = await showCoins('Fracked');
const raidaFailures = new Array(25).fill(0);

coins.coins.forEach(coin => {
    for (let i = 0; i < 25; i++) {
        if (coin.pown_string[i] === 'f' || coin.pown_string[i] === 'n') {
            raidaFailures[i]++;
        }
    }
});

raidaFailures.forEach((failures, raidaId) => {
    if (failures > 0) {
        console.log(`RAIDA ${raidaId}: ${failures} failures`);
    }
});

Denomination Reference

The denomination field uses integer codes that map to CloudCoin values:

Code  Value
----  -----------
  0   1
  1   5
  2   25
  3   100
  4   250
  5   1,000
  6   5,000
  7   25,000
  8   100,000
  9   250,000
 10   1,000,000
 11   Key/NFT/Special

Related Endpoints

/api/wallet/balance

Get summary balance information without individual coin details - faster for just checking total value.

/api/coins/fix

Repair fracked coins by re-authenticating with RAIDA servers to restore full authentication status.

/api/coins/detect

Authenticate coins with RAIDA network to update POWN strings and verify ownership.