/api/wallets/show-coins

GET

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

Description

The /api/wallets/show-coins endpoint scans a specified folder within the wallet at wallet_path and returns detailed information about every coin file. This is the live rest_core endpoint to use when you want to list serial numbers in a folder.

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.

🔁 Serial Number Listing

If you were looking for /api/tools/serial-numbers, use this endpoint instead. The current rest_core registers /api/wallets/show-coins for folder inventory and serial number listing.

Parameters

wallet_path string optional

Absolute path to the wallet to inspect.

Example: E:/Client_Data/Wallets/Default

Default: Uses the active/default wallet if not provided

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 wallet name derived from the wallet path.
total_coins integer
Total number of coins in the folder.
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 number
The coin's numeric denomination value as returned by rest_core (for example 100 or 250).
coins[].value number
The coin's numeric value. In the current rest_core implementation this matches coins[].denomination.
coins[].pown string
25-character authentication string showing status at each RAIDA (e.g., "ppppppppppppppppppppppppp" for fully authenticated).

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": 100,
      "value": 100,
      "pown": "ppppppppppppppppppppppppp"
    },
    {
      "serial_number": 67890,
      "denomination": 250,
      "value": 250,
      "pown": "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": 100,
      "value": 100,
      "pown": "ppppppppppppfnppppppppppp"
    },
    {
      "serial_number": 98765,
      "denomination": 250,
      "value": 250,
      "pown": "pppppppppppppppfppnpppppp"
    }
  ]
}

Example Error Response (Invalid Wallet Path)

{
  "status": "error",
  "message": "Invalid wallet_path",
  "error_code": 400
}

Example Error Response (Invalid Folder Name)

{
  "status": "error",
  "message": "Invalid folder name",
  "error_code": 400
}

Examples

JavaScript (fetch)

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

async function showCoins(walletPath = 'E:/Client_Data/Wallets/Default', folder = 'Bank') {
    try {
        const url = `${API_HOST}/api/wallets/show-coins?wallet_path=${encodeURIComponent(walletPath)}&folder=${encodeURIComponent(folder)}`;
        const response = await fetch(url);
        const result = await response.json();

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

            result.coins.forEach((coin, index) => {
                const passCount = (coin.pown.match(/p/g) || []).length;
                const failCount = (coin.pown.match(/f/g) || []).length;
                const noReplyCount = (coin.pown.match(/n/g) || []).length;
                const errorCount = (coin.pown.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}`);
                console.log(`  Status: ${passCount}/25 Pass, ${failCount}/25 Fail, ${noReplyCount}/25 No Reply, ${errorCount}/25 Error`);
                console.log('');
            });
            return result;
        } else {
            console.error('Failed to list coins:', result.message || result.error);
        }
    } catch (error) {
        console.error('Error listing coins:', error);
    }
}

// Show coins in Bank folder
showCoins('E:/Client_Data/Wallets/Default', 'Bank');

// Show coins that need fixing
// showCoins('E:/Client_Data/Wallets/Default', 'Fracked');

cURL

# Show coins in Bank folder
curl -X GET "http://localhost:8080/api/wallets/show-coins?wallet_path=E:/Client_Data/Wallets/Default&folder=Bank"

# Show coins in Fracked folder
curl -X GET "http://localhost:8080/api/wallets/show-coins?wallet_path=E:/Client_Data/Wallets/Default&folder=Fracked"

# Show coins in Import folder
curl -X GET "http://localhost:8080/api/wallets/show-coins?wallet_path=E:/Client_Data/Wallets/Default&folder=Import"

# Pretty print with jq
curl -X GET "http://localhost:8080/api/wallets/show-coins?wallet_path=E:/Client_Data/Wallets/Default&folder=Bank" | jq .

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 float64 `json:"denomination"`
    Value        float64 `json:"value"`
    Pown         string  `json:"pown"`
}

type ShowCoinsResponse struct {
    Status     string  `json:"status"`
    Operation  string  `json:"operation"`
    Folder     string  `json:"folder"`
    Wallet     string  `json:"wallet"`
    TotalCoins int     `json:"total_coins"`
    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/wallets/show-coins?wallet_path=E:/Client_Data/Wallets/Default&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
    }

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

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

        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.Pown)
        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('E:/Client_Data/Wallets/Default', '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('E:/Client_Data/Wallets/Default', 'Fracked');
frackedCoins.coins.forEach(coin => {
    const passCount = (coin.pown.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('E:/Client_Data/Wallets/Default', 'Fracked');
const raidaFailures = new Array(25).fill(0);

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

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

Value Fields

In the current rest_core implementation, both coins[].denomination and coins[].value are returned as the coin's numeric value rather than the internal denomination code.

Field           Example
--------------  -------
denomination    100
value           100

Other common values:
1, 5, 25, 100, 250, 1000, 5000, 25000, 100000, 250000, 1000000

Related Endpoints

/api/wallets/balance

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

/api/health/fix

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

/api/health/authenticate

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