/api/wallets/rename
GETRename 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.
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.
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
Response
Returns a JSON object with the rename operation result.
Success Response Properties
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
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:
- Parameter Check: Both 'wallet_path' and 'new_name' parameters must be provided
- Path Validation: Wallet path must be a valid string and not empty
- Path Existence: Wallet directory must exist on the filesystem
- Empty Name Check: New name cannot be empty string
- Same Name Check: Returns error if wallet already has the target name
- Conflict Check: No wallet with 'new_name' can exist in the same parent directory
- Filesystem Rename: Attempt to rename directory on filesystem
- Config Update: Update wallet configuration (wallet-locations.csv)
- Config Save: Save updated configuration to disk
Important Notes
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
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
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\OldName→C:\MyWallet3\NewName
Migration from legacy index-based API:
- Old API:
/api/wallets/active/rename?index=0&to=NewName(deprecated) - New API:
POST /api/wallets/renamewith 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.