/api/transactions/export-png
GETExport 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.
- Selects coins from Bank and Fracked folders using a greedy algorithm (largest denominations first)
- Builds the coin binary data (same format as a
.binfile) - Reads the PNG template image from the wallet's Templates folder
- Inserts a
cLDcchunk containing the coin data before the PNGIENDchunk - Writes the combined PNG to the destination folder
- Moves the original coin files from Bank/Fracked to the wallet's Exported folder
- Logs the transaction in
transactions.csv
- 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
.pngextension 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/depositendpoint
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
"success" for successful export operations."export-png".["100 CloudCoin 'AJ'.png"])."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
Returned when a required parameter is missing or invalid.
{
"status": "error",
"command": "export-png",
"error": "Missing required parameter: destination"
}
Common causes:
- Missing
amountordestinationparameter - Non-numeric or zero/negative
amount - Amount exceeds 1,000,000 CloudCoin maximum
- Insufficient funds in the wallet
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=trueand 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.)
cLDcchunk: A custom ancillary PNG chunk inserted beforeIENDthat contains the CloudCoin binary dataIENDchunk: 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.pngis 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
templateparameter 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
- Check wallet balance:
GET /api/wallets/balance - Export coins as PNG:
GET /api/transactions/export-png?amount=100&memo=AJ&destination=E:\coins&wallet_path=... - The exported
.pngfile appears at the destination - it looks like a normal image - Share the PNG file via email, messaging, social media, etc.
- 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-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.