/api/wallets/rename

GET

Rename a wallet by specifying its path and providing a new name. Updates both the filesystem directory and configuration.

Description

The `/api/wallets/rename` endpoint atomically renames a wallet by updating both the filesystem directory and the wallet configuration. This ensures consistency between the physical storage location and the wallet registry. Unlike the legacy index-based approach, this endpoint uses the wallet's filesystem path for precise identification.

⚠️ Atomic Operation

This endpoint performs an atomic rename operation that updates:

  • Filesystem: Renames the wallet directory on disk
  • Configuration: Updates the wallet-locations.csv file
  • Validation: Ensures no naming conflicts exist

If the filesystem rename succeeds but configuration save fails, an error is returned. Manual intervention may be required.

💡 Use Case

This endpoint is useful for:

  • Organizing wallets with descriptive names
  • Renaming wallets after project changes
  • Maintaining consistent naming conventions
  • Updating wallet names without losing data

Parameters

This endpoint requires two parameters passed as query string parameters.

Query String Parameters

wallet_path string required
The filesystem path to the wallet directory to rename. Can be an absolute path or relative to the CloudCoin data directory. Example: "E:\Data\Wallets\Default" on Windows or "/home/user/CloudCoin/Wallets/Default" on Linux/macOS, or just "Default" for relative path
new_name string required
New name for the wallet directory. Cannot be empty and must not already exist in the same parent directory. Only the final directory name changes, not the full path.

Response

Returns a JSON object with the rename operation result.

Success Response Properties

success boolean
Always true for successful rename.
message string
Human-readable success message.
old_path string
The original wallet filesystem path.
new_path string
The new wallet filesystem path after rename.
old_name string
The original wallet directory name.
new_name string
The new wallet directory name.

Success Response Example

{
  "success": true,
  "message": "Wallet renamed successfully",
  "old_path": "C:\\CloudCoin\\Default",
  "new_path": "C:\\CloudCoin\\NewName",
  "old_name": "Default",
  "new_name": "NewName"
}

Error Response Properties

success boolean
Always false for error responses.
error string
Human-readable error message describing what went wrong.
code integer
HTTP status code (400, 404, 409, or 500).

Error Response Examples

// 400 Bad Request - Missing parameter
{
  "success": false,
  "error": "Missing required parameter: wallet_path",
  "code": 400
}

// 404 Not Found - Wallet path does not exist
{
  "success": false,
  "error": "Wallet path does not exist: C:\\CloudCoin\\NonExistent",
  "code": 404
}

// 400 Bad Request - Empty new name
{
  "success": false,
  "error": "New wallet name cannot be empty",
  "code": 400
}

// 400 Bad Request - Same name as current
{
  "success": false,
  "error": "Wallet already has the name: Default",
  "code": 400
}

// 409 Conflict - Name already exists in parent directory
{
  "success": false,
  "error": "A wallet with the name 'NewName' already exists in that location",
  "code": 409
}

// 500 Internal Server Error - Filesystem rename failed
{
  "success": false,
  "error": "Failed to rename wallet directory on filesystem",
  "code": 500
}

// 500 Internal Server Error - Config save error
{
  "success": false,
  "error": "Failed to save wallet configuration after rename",
  "code": 500
}

Examples

JavaScript (fetch)

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

async function renameWallet(walletPath, newName) {
    try {
        const params = new URLSearchParams({
            wallet_path: walletPath,
            new_name: newName
        });

        const response = await fetch(`${API_HOST}/api/wallets/rename?${params}`, {
            method: 'GET'
        });

        const result = await response.json();

        if (result.success) {
            console.log('Wallet renamed successfully:');
            console.log(`Old path: ${result.old_path}`);
            console.log(`New path: ${result.new_path}`);
            console.log(`Old name: ${result.old_name}`);
            console.log(`New name: ${result.new_name}`);
        } else {
            console.error('Error:', result.error);
        }
    } catch (error) {
        console.error('Request failed:', error);
    }
}

// Example: Rename wallet at path - Windows
renameWallet('E:\\Data\\Wallets\\Default', 'ProductionWallet');

// Linux/macOS
// renameWallet('/home/user/CloudCoin/Wallets/Default', 'ProductionWallet');

// Or using relative path
renameWallet('Default', 'ProductionWallet');

cURL

# Rename wallet at absolute path to "ProductionWallet" - Windows
curl "http://localhost:8080/api/wallets/rename?wallet_path=E:\Data\Wallets\Default&new_name=ProductionWallet"

# Linux/macOS
# curl "http://localhost:8080/api/wallets/rename?wallet_path=/home/user/CloudCoin/Wallets/Default&new_name=ProductionWallet"

# Rename wallet at relative path with spaces in new name (URL-encoded)
curl "http://localhost:8080/api/wallets/rename?wallet_path=Default&new_name=My%20New%20Wallet"

Go

package main

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

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

type RenameResponse struct {
    Success bool   `json:"success"`
    Message string `json:"message"`
    OldPath string `json:"old_path"`
    NewPath string `json:"new_path"`
    OldName string `json:"old_name"`
    NewName string `json:"new_name"`
}

type ErrorResponse struct {
    Success bool   `json:"success"`
    Error   string `json:"error"`
    Code    int    `json:"code"`
}

func renameWallet(walletPath, newName string) error {
    // Build URL with query parameters
    params := url.Values{}
    params.Add("wallet_path", walletPath)
    params.Add("new_name", newName)

    fullURL := fmt.Sprintf("%s/api/wallets/rename?%s", ApiHost, params.Encode())

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

    bodyBytes, _ := ioutil.ReadAll(resp.Body)

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

    if result.Success {
        fmt.Printf("Success: %s\n", result.Message)
        fmt.Printf("Old path: %s\n", result.OldPath)
        fmt.Printf("New path: %s\n", result.NewPath)
        fmt.Printf("Old name: %s\n", result.OldName)
        fmt.Printf("New name: %s\n", result.NewName)
        return nil
    }

    return fmt.Errorf("API error (%d): %s", result.Code, result.Error)
}

func main() {
    // Windows
    if err := renameWallet("E:\\Data\\Wallets\\Default", "ProductionWallet"); err != nil {

    // Linux/macOS
    // if err := renameWallet("/home/user/CloudCoin/Wallets/Default", "ProductionWallet"); err != nil {
        fmt.Printf("Error: %v\n", err)
    }
}

Validation Rules

The endpoint performs several validation checks before renaming:

✓ Validation Steps
  1. Parameter Check: Both 'wallet_path' and 'new_name' parameters must be provided
  2. Path Validation: Wallet path must be a valid string and not empty
  3. Path Existence: Wallet directory must exist on the filesystem
  4. Empty Name Check: New name cannot be empty string
  5. Same Name Check: Returns error if wallet already has the target name
  6. Conflict Check: No wallet with 'new_name' can exist in the same parent directory
  7. Filesystem Rename: Attempt to rename directory on filesystem
  8. Config Update: Update wallet configuration (wallet-locations.csv)
  9. Config Save: Save updated configuration to disk

Important Notes

⚠️ Operation Atomicity

While the operation attempts to be atomic, if the filesystem rename succeeds but the configuration save fails (HTTP 500 with "Failed to save wallet configuration after rename"), the wallet directory will have the new name but the configuration will still reference the old name. In this case:

  • The wallet directory on disk has been renamed to the new name
  • The wallet-locations.csv still contains the old path/name
  • Manual correction may be required (rename directory back or edit config file)
  • Check file permissions on wallet-locations.csv
💡 Path-Based Identification

Unlike the legacy index-based system, this endpoint uses filesystem paths for wallet identification:

  • Paths can be absolute (e.g., C:\CloudCoin\Default) or relative (e.g., Default)
  • Relative paths are resolved within the CloudCoin data directory
  • Path matching is exact - no partial path matching
  • Returns 404 if the specified path does not exist
💡 Directory Contents Preservation

The rename operation preserves all wallet data:

  • All coins and subfolders (Bank, Fracked, Counterfeit, etc.) are preserved
  • Only the final directory name changes
  • All internal wallet data remains unchanged
  • Example: C:\MyWallet3\OldNameC:\MyWallet3\NewName
✓ Backward Compatibility

Migration from legacy index-based API:

  • Old API: /api/wallets/active/rename?index=0&to=NewName (deprecated)
  • New API: POST /api/wallets/rename with wallet_path and new_name
  • The old index-based endpoint may still be available for legacy support but is not recommended
  • New applications should use the path-based endpoint exclusively

Related Endpoints

/api/wallet/list

Get a complete list of all configured wallets with their names, locations, and coin counts.

/api/wallet/create

Create a new wallet with specified name and location path.

/api/wallet/delete

Delete a wallet by removing its directory and configuration entry.

/api/wallet/select

Set a wallet as the active wallet for subsequent operations.