/api/wallet/backup

GET

Creates a complete ZIP archive backup of the active wallet with timestamped filename.

Description

The `/api/wallet/backup` endpoint creates a complete ZIP archive of your active wallet, including all coins, transaction history, and configuration files. The backup is saved with a timestamped filename format: `CloudCoin-Wallet-Backup_{wallet_name}_{date}.zip`.

The backup includes:

  • Bank folder: All authenticated coins (13+ RAIDA passes)
  • Fracked folder: Partially authenticated coins (needs healing)
  • Counterfeit folder: Rejected coins
  • Import/Export folders: Incoming and outgoing coins
  • Receipts folder: Complete transaction logs
  • Data folder: transactions.csv and configuration files
💡 Best Practice

Schedule regular backups to prevent data loss. Store backups in multiple secure locations (encrypted drives, offline storage, cloud with encryption).

🔒 Security Notice

Backup files contain your complete wallet including all CloudCoin authenticity numbers (ANs). Store backups in secure, encrypted locations only. Anyone with access to a backup can access your coins.

Parameters

Parameter Type Required Description
destination string Yes Absolute path to the directory where the backup ZIP file will be saved. The directory will be created if it doesn't exist.
📝 Note

The destination parameter must be an absolute path (e.g., C:\Backups on Windows or /home/user/backups on Linux). Relative paths are not supported.

Response

Returns a JSON object with backup details including the full path to the created ZIP file.

Response Properties

status string
Always "success" for successful backups.
operation string
Always "backup".
wallet string
Name of the backed-up wallet.
destination string
Directory path where the backup was saved.
filename string
Name of the created ZIP file (format: CloudCoin-Wallet-Backup_{wallet}_{date}.zip).
full_path string
Complete filesystem path to the backup ZIP file.
message string
Human-readable success message.

Example Response (Success)

{
  "status": "success",
  "operation": "backup",
  "wallet": "Default",
  "destination": "C:\\Backups",
  "filename": "CloudCoin-Wallet-Backup_Default_2025-01-31.zip",
  "full_path": "C:\\Backups\\CloudCoin-Wallet-Backup_Default_2025-01-31.zip",
  "message": "Wallet backup created successfully"
}

Error Responses

Missing destination parameter (400 Bad Request)

{
  "status": "error",
  "error": "Missing required parameter: destination",
  "error_code": 1
}

No active wallet (400 Bad Request)

{
  "status": "error",
  "error": "No active wallet",
  "error_code": 8
}

Cannot create backup directory (500 Internal Server Error)

{
  "status": "error",
  "error": "Cannot create backup directory",
  "error_code": 101
}

Failed to create ZIP archive (500 Internal Server Error)

{
  "status": "error",
  "error": "Failed to create backup zip file",
  "error_code": 101
}

Examples

JavaScript (fetch)

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

async function backupWallet(destinationPath) {
    try {
        const params = new URLSearchParams({
            destination: destinationPath
        });

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

        if (result.status === 'success') {
            console.log('Backup created successfully!');
            console.log(`Wallet: ${result.wallet}`);
            console.log(`Filename: ${result.filename}`);
            console.log(`Full Path: ${result.full_path}`);
            console.log(`Message: ${result.message}`);
        } else {
            console.error('Backup failed:', result.error);
        }

        return result;
    } catch (error) {
        console.error('Error creating backup:', error);
        throw error;
    }
}

// Example: Create backup on Windows
backupWallet('C:\\Backups');

// Example: Create backup on Linux
backupWallet('/home/user/backups');

cURL

# Windows example
curl -X GET "http://localhost:8080/api/wallet/backup?destination=C:\Backups"

# Linux example
curl -X GET "http://localhost:8080/api/wallet/backup?destination=/home/user/backups"

# With URL encoding for special characters
curl -X GET "http://localhost:8080/api/wallet/backup?destination=%2Fhome%2Fuser%2Fbackups"

Go

package main

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

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

type BackupResponse struct {
    Status      string `json:"status"`
    Operation   string `json:"operation"`
    Wallet      string `json:"wallet"`
    Destination string `json:"destination"`
    Filename    string `json:"filename"`
    FullPath    string `json:"full_path"`
    Message     string `json:"message"`
}

type ErrorResponse struct {
    Status    string `json:"status"`
    Error     string `json:"error"`
    ErrorCode int    `json:"error_code"`
}

func backupWallet(destination string) (*BackupResponse, error) {
    // Build URL with query parameters
    params := url.Values{}
    params.Add("destination", destination)

    url := fmt.Sprintf("%s/api/wallet/backup?%s", ApiHost, params.Encode())

    resp, err := http.Get(url)
    if err != nil {
        return nil, fmt.Errorf("request failed: %w", err)
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, fmt.Errorf("failed to read response: %w", err)
    }

    // Check for error response
    if resp.StatusCode != http.StatusOK {
        var errResp ErrorResponse
        if err := json.Unmarshal(body, &errResp); err != nil {
            return nil, fmt.Errorf("failed to parse error response: %w", err)
        }
        return nil, fmt.Errorf("backup failed: %s (code %d)", errResp.Error, errResp.ErrorCode)
    }

    var result BackupResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, fmt.Errorf("failed to parse response: %w", err)
    }

    return &result, nil
}

func main() {
    // Example: Create backup
    destination := "C:\\Backups"  // Windows
    // destination := "/home/user/backups"  // Linux

    result, err := backupWallet(destination)
    if err != nil {
        fmt.Printf("Error: %v\n", err)
        return
    }

    fmt.Printf("Backup created successfully!\n")
    fmt.Printf("Wallet: %s\n", result.Wallet)
    fmt.Printf("Filename: %s\n", result.Filename)
    fmt.Printf("Full Path: %s\n", result.FullPath)
    fmt.Printf("Message: %s\n", result.Message)
}

Backup Process Details

The backup process follows these steps:

  1. Validate Parameters: Checks that destination path is provided and not empty
  2. Verify Active Wallet: Ensures a wallet is currently active
  3. Generate Filename: Creates timestamped filename with format: CloudCoin-Wallet-Backup_{wallet_name}_{YYYY-MM-DD}.zip
  4. Create Directory: Creates destination directory if it doesn't exist (with appropriate permissions)
  5. Archive Wallet: Uses platform-specific ZIP compression (PowerShell on Windows, zip command on Linux/Unix)
  6. Verify Success: Checks that ZIP file was created successfully
  7. Return Details: Returns JSON response with full path and metadata
💡 Filename Format

The backup filename includes both the wallet name and date for easy identification. Example: CloudCoin-Wallet-Backup_Default_2025-01-31.zip

This makes it simple to track multiple backups across different wallets and dates.

Restoring from Backup

To restore a wallet from a backup ZIP file:

  1. Extract ZIP: Unzip the backup file to a new directory
  2. Add Location: Use /api/wallet/add-location to register the extracted wallet
  3. Switch Wallet: Use /api/wallet/switch to make it the active wallet
  4. Verify Balance: Use /api/wallet/balance to confirm all coins are present
📝 Verification After Restore

After restoring a wallet, verify the coin count and balance match the pre-backup state. You may want to run /api/wallet/show-coins to inspect individual coins.

Related Endpoints

/api/wallet/add-location

Register a new wallet location or restore a wallet from backup by adding its extracted directory.

/api/wallet/show-coins

View all coins in the active wallet before creating a backup to verify contents.

/api/wallet/balance

Check wallet balance before and after backup/restore to verify coin integrity.