/api/wallet/add-location

Description

The `/api/wallet/add-location` endpoint creates a new wallet storage location at the specified filesystem path. It automatically creates a "Default" wallet at that location with the complete folder structure required for CloudCoin operations (Bank, Fracked, Counterfeit, Import, Export, Receipts, etc.).

Request Body

Send a JSON object with the following property:

{
  "path": "C:\\MyWallets"
}

Response

Returns a JSON object confirming the wallet location was added and the Default wallet was created.

{
  "status": "success",
  "operation": "wallet-add-location",
  "location": "C:\\MyWallets",
  "wallet": "Default",
  "wallet_path": "C:\\MyWallets\\Default",
  "message": "Wallet location added successfully and set as active",
  "note": "Created 'Default' wallet in this location"
}

Error Responses

The endpoint returns specific error messages for various failure scenarios:

{
  "status": "error",
  "operation": "wallet-add-location",
  "message": "Missing or invalid 'path' in request body",
  "error_code": 400
}

{
  "status": "error",
  "operation": "wallet-add-location",
  "message": "Path cannot be empty",
  "error_code": 400
}

{
  "status": "error",
  "operation": "wallet-add-location",
  "message": "Path exists but is not a directory",
  "error_code": 400
}

{
  "status": "error",
  "operation": "wallet-add-location",
  "message": "Failed to create directory - check permissions and path validity",
  "error_code": 500
}

{
  "status": "error",
  "operation": "wallet-add-location",
  "message": "Failed to create wallet structure",
  "error_code": 500
}

{
  "status": "error",
  "operation": "wallet-add-location",
  "message": "Failed to save wallet-locations.csv",
  "error_code": 500
}

Process Flow

The endpoint performs the following steps in sequence:

1. Extract path: Extracts the 'path' parameter from the JSON request body
2. Validate path: Trims whitespace and verifies the path is not empty
3. Check existence: Checks if the path already exists on the filesystem
   • If exists: Verifies it's a directory (not a file)
   • If doesn't exist: Creates the directory with appropriate permissions (Unix: 0755)
4. Create Default wallet: Creates a "Default" subdirectory at [path]/Default
5. Build folder structure: Creates all required subdirectories:
   • Bank/ (authenticated coins)
   • Fracked/ (partially failed coins)
   • Counterfeit/ (rejected coins)
   • Limbo/ (uncertain status)
   • Import/ (incoming coins)
   • Export/ (outgoing coins)
   • Receipts/ (transaction logs)
6. Update configuration: Adds the Default wallet to the global configuration with properties:
   • wallet_name = "Default"
   • location_path = [specified path]
   • auto_mount = true
7. Save to CSV: Persists the configuration to wallet-locations.csv
8. Set as active: Places the new wallet at index 0 (makes it the active wallet)

Examples

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

async function addWalletLocation(walletPath) {
    try {
        const response = await fetch(`${API_HOST}/api/wallet/add-location`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json'
            },
            body: JSON.stringify({
                path: walletPath
            })
        });

        const result = await response.json();

        if (result.status === 'success') {
            console.log('Wallet location added successfully!');
            console.log(`Location: ${result.location}`);
            console.log(`Wallet: ${result.wallet}`);
            console.log(`Full Path: ${result.wallet_path}`);
            console.log(`Message: ${result.message}`);
            console.log(`Note: ${result.note}`);
        } else {
            console.error('Error adding wallet location:', result.message);
        }

        return result;
    } catch (error) {
        console.error('Network error:', error);
        throw error;
    }
}

// Example: Add wallet on Windows C: drive
addWalletLocation('C:\\MyWallets');

// Example: Add wallet on different drive
addWalletLocation('D:\\CloudCoin\\Wallets');

// Example: Add wallet on network share
addWalletLocation('\\\\server\\share\\wallets');

# Add wallet location on Windows
curl -X POST "http://localhost:8080/api/wallet/add-location" \
  -H "Content-Type: application/json" \
  -d "{\"path\":\"C:\\\\MyWallets\"}"

# Add wallet location on Linux/Unix
curl -X POST "http://localhost:8080/api/wallet/add-location" \
  -H "Content-Type: application/json" \
  -d '{"path":"/home/user/wallets"}'

# Add wallet on different drive
curl -X POST "http://localhost:8080/api/wallet/add-location" \
  -H "Content-Type: application/json" \
  -d "{\"path\":\"D:\\\\CloudCoin\\\\Storage\"}"

package main

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

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

type AddLocationRequest struct {
    Path string `json:"path"`
}

type AddLocationResponse struct {
    Status      string `json:"status"`
    Operation   string `json:"operation"`
    Location    string `json:"location"`
    Wallet      string `json:"wallet"`
    WalletPath  string `json:"wallet_path"`
    Message     string `json:"message"`
    Note        string `json:"note"`
}

func addWalletLocation(walletPath string) (*AddLocationResponse, error) {
    reqBody := AddLocationRequest{
        Path: walletPath,
    }

    jsonData, err := json.Marshal(reqBody)
    if err != nil {
        return nil, err
    }

    resp, err := http.Post(
        fmt.Sprintf("%s/api/wallet/add-location", ApiHost),
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

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

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

    return &result, nil
}

func main() {
    // Add wallet location
    result, err := addWalletLocation("C:\\MyWallets")
    if err != nil {
        panic(err)
    }

    if result.Status == "success" {
        fmt.Println("Wallet location added successfully!")
        fmt.Printf("Location: %s\n", result.Location)
        fmt.Printf("Wallet: %s\n", result.Wallet)
        fmt.Printf("Full Path: %s\n", result.WalletPath)
        fmt.Printf("Message: %s\n", result.Message)
        fmt.Printf("Note: %s\n", result.Note)
    } else {
        fmt.Printf("Error: %s\n", result.Message)
    }
}

Folder Structure Created

When you add a wallet location at C:\MyWallets, the following directory structure is automatically created:

C:\MyWallets\
└── Default\
    ├── Bank\           (Authenticated coins - ready to spend)
    ├── Fracked\        (Partially failed coins - need healing)
    ├── Counterfeit\    (Rejected coins - failed authentication)
    ├── Limbo\          (Uncertain status - retry needed)
    ├── Import\         (Incoming coins - drop files here)
    ├── Export\         (Outgoing coins - exported files)
    └── Receipts\       (Transaction logs and receipts)

Use Cases

// Primary wallet on C: drive
await addWalletLocation('C:\\Wallets');

// Backup wallet on D: drive
await addWalletLocation('D:\\CloudCoin\\Backup');

// Archive wallet on E: drive
await addWalletLocation('E:\\Archive\\CloudCoin');

// Network share wallet
await addWalletLocation('\\\\fileserver\\cloudcoin\\shared');

// Personal network drive
await addWalletLocation('\\\\nas\\users\\alice\\wallet');

// VeraCrypt mounted volume
await addWalletLocation('V:\\SecureWallet');

// BitLocker encrypted drive
await addWalletLocation('E:\\Encrypted\\CloudCoin');