CloudCoin > API Reference > /api/coins/unpack

/api/coins/unpack

GET

Extract individual coins from multi-coin container files and image formats.

http://localhost:8080/api/coins/unpack

Description

The `/api/coins/unpack` endpoint scans the Import folder for container files (multi-coin binary files, stack files, JPEG, PNG, and ZIP archives) and extracts individual coins to separate .bin files in the Suspect folder. This is the first step in importing coins from external sources.

The command processes multiple file formats:

  • Binary files (.bin) - Multi-coin binary format (file format 9, token_count > 1)
  • Stack files (.stack) - Legacy CloudCoin v1/v2 multi-coin format
  • JPEG images (.jpg, .jpeg) - Coins embedded in JPEG metadata
  • PNG images (.png) - Coins embedded in PNG chunks
  • ZIP archives (.zip) - Compressed coin containers
Workflow Integration

Unpacking is typically the first step in the coin import workflow:

  1. Unpack: Extract individual coins from containers → Suspect folder
  2. Authenticate: Verify coins with RAIDA servers → POWN strings updated
  3. Grade: Sort coins to Bank/Fracked/Counterfeit based on authentication

Parameters

This endpoint does not require any parameters. It automatically processes all files in the Import folder of the active wallet.

Operation Details

File Processing Sequence

The unpack operation follows this sequence:

Step 1: Extract ZIP Archives

All .zip files are extracted to the Import folder, then moved to Imported folder.

Step 2: Extract PNG Images

Coins embedded in PNG files are extracted to Suspect folder with Task ID in filename. Original PNG files are moved to Imported folder.

Step 3: Process Binary Files

Binary files (.bin) are analyzed by version:

  • Version 3 (Current): Multi-coin files are split into individual coins in Suspect folder. Parent file moves to Imported.
  • Version 2 (Legacy): Moved to Import/Version2 subfolder for conversion.
  • Version 1 (Legacy): Stack files moved to Import/Version1 subfolder.
  • Corrupted: Invalid files moved to Corrupted folder.

Step 4: Handle Duplicates

If a coin with the same serial number already exists in the wallet (Bank/Fracked folders), the extracted coin is moved to Duplicates folder instead of Suspect.

UnpackLog.csv Tracking

Every unpack operation creates a detailed log file at Imported/Unpack_Logs/UnpackLog_YYYY-MM-DD_HH-MM-SS.csv with the following format:

Relation,Name,Destination
P,100 CloudCoin #12345.bin,Imported
C,100 CloudCoin #12345_coin1 'Jan-06-25_03-45-30-PM'.bin,Suspect
C,100 CloudCoin #12345_coin2 'Jan-06-25_03-45-30-PM'.bin,Suspect
P,coins.zip,Imported
C,5 CloudCoin #67890 'Jan-06-25_03-45-30-PM'.bin,Suspect
P (Parent)
Files that existed before the unpack command started. These are the original container files.
C (Child)
Files created during the unpack operation. These are the extracted individual coins.

Task ID System

All extracted coins include a Task ID in their filename memo field (between quotes). This allows tracking which coins came from the same unpack operation. The Task ID format is: MMM-DD-YY_HH-MM-SS-AM/PM (e.g., "Jan-06-25_03-45-30-PM").

Response

Returns a JSON object indicating the unpack operation status.

Success Response Properties

status string
Always "success" when operation completes.
operation string
Always "coins-unpack".
message string
Human-readable status message.
wallet string
Name of the active wallet where coins were unpacked.
note string
Additional information about the operation results.

Example Success Response

{
  "status": "success",
  "operation": "coins-unpack",
  "message": "Unpack operation completed",
  "wallet": "Default",
  "note": "Container files unpacked to individual coins in Suspect folder"
}

Error Responses

No Active Wallet (400)

{
  "error": "No active wallet"
}

Returned when no wallet is currently active. Use `/api/wallet/load` to activate a wallet first.

Operation Failed (500)

{
  "error": "Unpack operation failed"
}

Returned when the unpack operation encounters a critical error (file system issues, permissions, etc.).

Examples

JavaScript (fetch)

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

async function unpackCoins() {
    try {
        console.log('Starting unpack operation...');

        const response = await fetch(`${API_HOST}/api/coins/unpack`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log('Unpack completed successfully!');
            console.log(`Wallet: ${result.wallet}`);
            console.log(`Note: ${result.note}`);

            // Next step: Authenticate the unpacked coins
            console.log('Next: Run /api/coins/authenticate to verify coins');
        } else {
            console.error('Unpack failed:', result.error);
        }
    } catch (error) {
        console.error('Error unpacking coins:', error);
    }
}

unpackCoins();

cURL

# Unpack coins from Import folder
curl -X GET "http://localhost:8080/api/coins/unpack"

# Example: Complete import workflow
# Step 1: Unpack container files
curl -X GET "http://localhost:8080/api/coins/unpack"

# Step 2: Authenticate unpacked coins
curl -X GET "http://localhost:8080/api/coins/authenticate"

# Step 3: Grade coins to Bank/Fracked/Counterfeit
curl -X GET "http://localhost:8080/api/coins/grade"

Go

package main

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

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

type UnpackResponse struct {
    Status    string `json:"status"`
    Operation string `json:"operation"`
    Message   string `json:"message"`
    Wallet    string `json:"wallet"`
    Note      string `json:"note"`
    Error     string `json:"error,omitempty"`
}

func unpackCoins() error {
    resp, err := http.Get(fmt.Sprintf("%s/api/coins/unpack", ApiHost))
    if err != nil {
        return err
    }
    defer resp.Body.Close()

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

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

    if result.Status == "success" {
        fmt.Println("Unpack completed successfully!")
        fmt.Printf("Wallet: %s\n", result.Wallet)
        fmt.Printf("Note: %s\n", result.Note)
        fmt.Println("\nNext steps:")
        fmt.Println("1. Run /api/coins/authenticate to verify coins")
        fmt.Println("2. Run /api/coins/grade to sort coins")
    } else {
        return fmt.Errorf("unpack failed: %s", result.Error)
    }

    return nil
}

func main() {
    if err := unpackCoins(); err != nil {
        panic(err)
    }
}

Folder Structure After Unpack

After running the unpack operation, your wallet structure will look like this:

Wallets/Default/
├── Bank/                    (authenticated coins - 13+ passes)
├── Fracked/                 (partially authenticated - <13 passes)
├── Counterfeit/             (failed authentication)
├── Suspect/                 ← Individual coins extracted here
│   ├── 100 CloudCoin #12345_coin1 'Jan-06-25_03-45-30-PM'.bin
│   ├── 100 CloudCoin #12345_coin2 'Jan-06-25_03-45-30-PM'.bin
│   └── 5 CloudCoin #67890 'Jan-06-25_03-45-30-PM'.bin
├── Duplicates/              (coins with duplicate serial numbers)
├── Corrupted/               (invalid/corrupted files)
├── Import/                  (empty after unpack)
│   ├── Version1/            (legacy v1 stack files)
│   └── Version2/            (legacy v2 binary files)
├── Imported/                ← Parent container files moved here
│   ├── 100 CloudCoin #12345.bin
│   ├── coins.zip
│   ├── image.png
│   └── Unpack_Logs/
│       └── UnpackLog_2025-01-06_15-45-30.csv
└── Trash/                   (unknown file types)

Related Endpoints

/api/coins/import

Import coins from external sources to the Import folder before unpacking.

View Details

/api/coins/authenticate

Authenticate unpacked coins with RAIDA servers to verify authenticity.

View Details

/api/coins/grade

Sort authenticated coins to Bank, Fracked, or Counterfeit folders based on POWN status.

View Details

/api/wallet/show-coins

View all coins in the wallet including unpacked coins in the Suspect folder.

View Details

Best Practices

Recommended Workflow
  • Check Import folder: Ensure you have container files to unpack before running this endpoint.
  • Run sequentially: Always unpack → authenticate → grade in that order.
  • Check logs: Review UnpackLog.csv to see parent/child relationships and track file movements.
  • Handle duplicates: Coins with duplicate serial numbers are moved to Duplicates folder automatically.
  • Verify extraction: Use `/api/wallet/show-coins` with folder=Suspect to see unpacked coins.
  • Clean up: After successful authentication and grading, the Import folder should be empty and Imported folder contains processed containers.

File Format Support Details

Binary Files (.bin)

Format: CloudCoin binary format version 3 (file format 9)

Detection: Checks file header for format ID and coin count

Processing: If token_count > 1, splits into individual coins

Output: Each coin saved as separate .bin file in Suspect folder

Stack Files (.stack)

Format: Legacy CloudCoin v1 format

Detection: File extension .stack

Processing: Moved to Import/Version1 subfolder for conversion

Note: Requires separate conversion step (not yet implemented)

JPEG Images (.jpg, .jpeg)

Format: Coins embedded in JPEG EXIF metadata

Detection: Scans JPEG metadata sections

Processing: Extracts embedded coin data to separate .bin files

Output: Original JPEG moved to Imported, extracted coins in Suspect

PNG Images (.png)

Format: Coins embedded in PNG chunks

Detection: Scans PNG chunk types for coin data

Processing: Extracts embedded coin data to separate .bin files

Output: Original PNG moved to Imported, extracted coins in Suspect

ZIP Archives (.zip)

Format: Standard ZIP compression

Detection: File extension .zip

Processing: Extracts all contents to Import folder, then processes extracted files

Output: ZIP file moved to Imported after extraction