/api/transactions/export-png

GET

Export CloudCoins embedded in a PNG image file for sharing or transfer.

Description

The /api/transactions/export-png endpoint works the same as /api/transactions/export except the exported coin data is embedded inside a PNG image file instead of being written as a raw .bin file.

The coin binary data is stored in a custom cLDc (CloudCoin Data) chunk inserted before the PNG's IEND marker. The resulting file is a valid PNG image that can be viewed normally, but also contains the CloudCoin data which can be extracted during import/deposit.

How It Works
  1. Selects coins from Bank and Fracked folders using a greedy algorithm (largest denominations first)
  2. Builds the coin binary data (same format as a .bin file)
  3. Reads the PNG template image from the wallet's Templates folder
  4. Inserts a cLDc chunk containing the coin data before the PNG IEND chunk
  5. Writes the combined PNG to the destination folder
  6. Moves the original coin files from Bank/Fracked to the wallet's Exported folder
  7. Logs the transaction in transactions.csv
Important Notes
  • Exported coins are moved out of Bank/Fracked into the Exported folder. They are no longer spendable from this wallet.
  • The output file has a .png extension and is a valid PNG image
  • A PNG template must exist in the wallet's Templates folder. Use the default template or import a custom one.
  • Maximum export: 1,000,000 CloudCoin per request and 1,000 notes per file
  • The destination folder is created automatically if it does not exist
  • PNG files with embedded coins can be imported using the standard /api/transactions/deposit endpoint

Parameters

All parameters are passed as URL query parameters.

Parameter Type Required Description
amount number Yes Amount of CloudCoin to export in whole units (e.g., 100, 250). Must be positive and no greater than 1,000,000.
destination string Yes Full path to the destination folder where the exported .png file will be written (e.g., E:\coins, F:\export). The folder is created if it does not exist.
wallet_path string No Path to the wallet to export from. If not specified, uses the default wallet.
memo string No A label included in the exported filename inside single quotes. For example, memo=AJ produces 100 CloudCoin 'AJ'.png. If set to random, a random hex ID is generated. If omitted, the filename has no label (e.g., 100 CloudCoin.png). Also used as the memo in the transaction log.
template string No Path to a specific PNG template file to use. If omitted, uses the wallet's active template (or default.png).
auto_change boolean No If true or 1, automatically break a larger coin to make change when the exact amount is not available. Requires a RAIDA round-trip. Default: false.
tag string No Alias for memo. If both are provided, memo takes priority.

Response

Returns a JSON object with export operation results.

Success Response Properties

status string
Always "success" for successful export operations.
command string
Always "export-png".
files_created integer
Number of PNG files created (typically 1).
coins_exported integer
Total number of coin notes embedded in the PNG file.
value_exported number
Total value exported in whole CloudCoin units (e.g., 100.0).
files array
Array of created filenames (e.g., ["100 CloudCoin 'AJ'.png"]).
template string
Name of the PNG template used (e.g., "default.png").

Success Response Example

{
  "status": "success",
  "command": "export-png",
  "files_created": 1,
  "coins_exported": 2,
  "value_exported": 100,
  "template": "default.png",
  "files": [
    "100 CloudCoin 'AJ'.png"
  ]
}

Success Response (no memo)

{
  "status": "success",
  "command": "export-png",
  "files_created": 1,
  "coins_exported": 1,
  "value_exported": 250,
  "template": "default.png",
  "files": [
    "250 CloudCoin.png"
  ]
}

Error Responses

400 Bad Request

Returned when a required parameter is missing or invalid.

{
  "status": "error",
  "command": "export-png",
  "error": "Missing required parameter: destination"
}

Common causes:

  • Missing amount or destination parameter
  • Non-numeric or zero/negative amount
  • Amount exceeds 1,000,000 CloudCoin maximum
  • Insufficient funds in the wallet
500 Internal Server Error

Returned when the export operation fails due to an internal error.

{
  "status": "error",
  "command": "export-png",
  "error": "PNG template not found",
  "wallet_path": "E:\\Client_Data\\Wallets\\Default",
  "destination": "E:\\coins",
  "amount_requested": 100
}

Common causes:

  • No PNG template found in the wallet's Templates folder
  • Selected coin count exceeds 1,000 notes
  • File I/O errors writing to the destination folder
  • Change-making failed (when auto_change=true and RAIDA is unreachable)

Filename Format

The exported PNG file is named the same way as a regular export, but with a .png extension:

Scenario Filename
Single coin, with memo 100 CloudCoin 'AJ'.png
Multiple coins, with memo 100 CloudCoin [5 coins] 'AJ'.png
Single coin, no memo 100 CloudCoin.png
Multiple coins, no memo 100 CloudCoin [5 coins].png
memo=random 100 CloudCoin 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'.png

PNG Format Details

The exported PNG file is structured as follows:

  • PNG header and image data: Standard PNG chunks from the template image (IHDR, IDAT, etc.)
  • cLDc chunk: A custom ancillary PNG chunk inserted before IEND that contains the CloudCoin binary data
  • IEND chunk: Standard PNG end marker

cLDc Chunk Structure

Field Size Description
Length 4 bytes Big-endian length of the data portion (excludes type and CRC)
Type 4 bytes cLDc (0x634C4463) - CloudCoin Data chunk
Data variable 32-byte file header + coin bodies (same format as .bin files)
CRC 4 bytes CRC-32 of the type + data fields

Because the cLDc chunk type starts with a lowercase letter, it is treated as an ancillary (non-critical) chunk by all PNG viewers. Image viewers will display the template image normally and ignore the embedded coin data.

PNG Templates

Each wallet has a Templates folder containing PNG images used as the visual carrier for exported coins. The template is the image that users see when they view the exported file.

  • Default template: default.png is always available in every wallet
  • Custom templates: Import your own PNG images to use as templates
  • Active template: The last-used template is remembered and used by default
  • Override per-request: Use the template parameter to specify a different template

Examples

cURL

# Export 100 CC as PNG with memo "AJ"
curl "http://localhost:8080/api/transactions/export-png?amount=100&memo=AJ&destination=E:\coins&wallet_path=E:/Data/Wallets/Default"

# Export 250 CC as PNG with no memo
curl "http://localhost:8080/api/transactions/export-png?amount=250&destination=F:\export&wallet_path=E:/Data/Wallets/Default"

# Export with a custom PNG template
curl "http://localhost:8080/api/transactions/export-png?amount=50&memo=Gift&template=E:/templates/birthday.png&destination=E:\coins&wallet_path=E:/Data/Wallets/Default"

# Export with automatic change-making
curl "http://localhost:8080/api/transactions/export-png?amount=3&memo=Test&destination=E:\coins&auto_change=true&wallet_path=E:/Data/Wallets/Default"

JavaScript (fetch)

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

async function exportPng(amount, destination, walletPath, memo = null, template = null, autoChange = false) {
    const params = new URLSearchParams({
        amount: amount,
        destination: destination
    });

    if (walletPath) params.append('wallet_path', walletPath);
    if (memo) params.append('memo', memo);
    if (template) params.append('template', template);
    if (autoChange) params.append('auto_change', 'true');

    const response = await fetch(`${API_HOST}/api/transactions/export-png?${params}`);
    const result = await response.json();

    if (result.status === 'success') {
        console.log(`Exported ${result.coins_exported} coins (${result.value_exported} CC) as PNG`);
        console.log(`File: ${result.files[0]}`);
        console.log(`Template: ${result.template}`);
    } else {
        console.error('Export failed:', result.error);
    }

    return result;
}

// Export 100 CC as PNG with memo
await exportPng(100, 'E:\\coins', 'E:/Data/Wallets/Default', 'AJ');

// Export with custom template
await exportPng(50, 'E:\\coins', 'E:/Data/Wallets/Default', 'Gift', 'E:/templates/birthday.png');

// Export with no memo (clean filename)
await exportPng(250, 'F:\\export', 'E:/Data/Wallets/Default');

Go

package main

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

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

type ExportPngResponse struct {
    Status        string   `json:"status"`
    Command       string   `json:"command"`
    FilesCreated  int      `json:"files_created"`
    CoinsExported int      `json:"coins_exported"`
    ValueExported float64  `json:"value_exported"`
    Template      string   `json:"template"`
    Files         []string `json:"files"`
    Error         string   `json:"error,omitempty"`
}

func exportPng(amount int, destination, walletPath, memo, template string) (*ExportPngResponse, error) {
    params := url.Values{}
    params.Add("amount", fmt.Sprintf("%d", amount))
    params.Add("destination", destination)

    if walletPath != "" {
        params.Add("wallet_path", walletPath)
    }
    if memo != "" {
        params.Add("memo", memo)
    }
    if template != "" {
        params.Add("template", template)
    }

    reqURL := fmt.Sprintf("%s/api/transactions/export-png?%s", ApiHost, params.Encode())

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

    body, err := io.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }

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

    return &result, nil
}

func main() {
    // Export 100 CC as PNG with memo
    result, err := exportPng(100, `E:\coins`, "E:/Data/Wallets/Default", "AJ", "")
    if err != nil {
        panic(err)
    }
    fmt.Printf("Exported %d coins (%.0f CC) as PNG\n", result.CoinsExported, result.ValueExported)
    fmt.Printf("File: %s\n", result.Files[0])
    fmt.Printf("Template: %s\n", result.Template)
}

Transaction Logging

Every successful PNG export is recorded in the wallet's transactions.csv file with:

  • Symbol: Withdraw symbol
  • Type: "Export"
  • Amount: Negative value (debit) matching the exported amount
  • Description: The memo text, or "Export" if no memo was provided
  • Balance: Updated wallet balance after the export

Workflow Example

Typical PNG Export Workflow
  1. Check wallet balance: GET /api/wallets/balance
  2. Export coins as PNG: GET /api/transactions/export-png?amount=100&memo=AJ&destination=E:\coins&wallet_path=...
  3. The exported .png file appears at the destination - it looks like a normal image
  4. Share the PNG file via email, messaging, social media, etc.
  5. Recipient imports the PNG using: GET /api/transactions/deposit (drop the PNG into the Import folder)

Comparison: Export vs Export-PNG

Feature /api/transactions/export /api/transactions/export-png
Output format .bin (raw binary) .png (image with embedded data)
Viewable as image No Yes - displays the template image
File size Smaller (~439 bytes per coin) Larger (template image + coin data)
Sharing File transfer, email attachment Anywhere images are accepted (social media, chat, email)
Import method Both imported the same way via /api/transactions/deposit
Requires template No Yes - PNG template in wallet's Templates folder

Related Endpoints

/api/transactions/export

Export CloudCoins as a raw .bin file (without PNG embedding).

/api/transactions/export-locations

Retrieve the list of previously used export destinations for a dropdown menu.

/api/transactions/deposit

Import and authenticate CloudCoin files (including PNG files) into a wallet.