/api/transactions/export

GET

Export CloudCoins from a specified wallet to a destination folder for sharing or transfer.

Description

The /api/transactions/export endpoint exports CloudCoins from a specified wallet's Bank and Fracked folders to a destination folder. All exported coins are combined into a single .bin file. The original coin files are moved to the wallet's Exported folder after a successful export.

How It Works
  1. Selects coins from Bank and Fracked folders using a greedy algorithm (largest denominations first)
  2. Combines all selected coins into a single .bin file at the destination
  3. Moves the original coin files from Bank/Fracked to the wallet's Exported folder
  4. Logs the transaction in transactions.csv
  5. Saves the destination path to export locations history
Important Notes
  • Exported coins are moved out of Bank/Fracked into the Exported folder. They are no longer spendable from this wallet.
  • The amount parameter is in whole CloudCoin units (e.g., 1, 5, 25, 100, 250)
  • Maximum export: 1,000,000 CloudCoin per request and 1,000 notes per file
  • If the exact amount cannot be assembled from available coins, the endpoint returns an error unless auto_change=true is set
  • The destination folder is created automatically if it does not exist

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 .bin 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'.bin. If set to random, a random hex ID is generated. If omitted, the filename has no label (e.g., 100 CloudCoin.bin). Also used as the memo in the transaction log.
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 "coins-export".
files_created integer
Number of export files created (typically 1).
coins_exported integer
Total number of coin notes written to the export 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'.bin"]).

Success Response Example

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

Success Response (no memo)

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

Success Response (memo=random)

{
  "status": "success",
  "command": "coins-export",
  "files_created": 1,
  "coins_exported": 5,
  "value_exported": 100,
  "files": [
    "100 CloudCoin [5 coins] 'a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6'.bin"
  ]
}

Error Responses

400 Bad Request

Returned when a required parameter is missing or invalid.

{
  "status": "error",
  "command": "coins-export",
  "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": "coins-export",
  "error": "RESULT_ERROR",
  "wallet_path": "E:\\Client_Data\\Wallets\\Default",
  "destination": "E:\\coins",
  "amount_requested": 100
}

Common causes:

  • Selected coin count exceeds 1,000 notes (too many small denominations)
  • File I/O errors writing to the destination folder
  • Change-making failed (when auto_change=true and RAIDA is unreachable)

Filename Format

The exported file is named based on the total value, number of coins, and the memo:

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

Examples

cURL

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

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

# Export with random ID in filename
curl "http://localhost:8080/api/transactions/export?amount=50&memo=random&destination=E:\coins&wallet_path=E:/Data/Wallets/Default"

# Export with automatic change-making
curl "http://localhost:8080/api/transactions/export?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 exportCoins(amount, destination, walletPath, memo = 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 (autoChange) params.append('auto_change', 'true');

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

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

    return result;
}

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

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

// Export with random filename tag
await exportCoins(50, 'E:\\coins', 'E:/Data/Wallets/Default', 'random');

Go

package main

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

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

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

func exportCoins(amount int, destination, walletPath, memo string) (*ExportResponse, 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)
    }

    reqURL := fmt.Sprintf("%s/api/transactions/export?%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 ExportResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

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

Transaction Logging

Every successful 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 Export Workflow
  1. Check wallet balance: GET /api/wallets/balance
  2. Optionally check previous export locations: GET /api/transactions/export-locations
  3. Export coins: GET /api/transactions/export?amount=100&memo=AJ&destination=E:\coins&wallet_path=...
  4. The exported .bin file appears at the destination
  5. Share the file with the recipient
  6. Recipient imports using: GET /api/transactions/deposit

File Format

Exported files use CloudCoin Version 3 binary format (.bin):

  • File extension: .bin
  • Structure: Standard CCv3 binary with file header + coin bodies
  • Per-coin size: 439 bytes
  • Maximum file size: ~430 KB (1,000 coins x 439 bytes)
  • Multi-coin: All exported coins are combined into a single file

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 into a wallet.

/api/wallets/balance

Check current wallet balance before exporting to verify sufficient funds.