/api/wallet/rename

GET

Rename a wallet by updating both the filesystem directory and configuration.

Description

The `/api/wallet/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.

⚠️ 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 query parameters.

Query Parameters

from string required
Current name of the wallet to rename. Must match an existing wallet in wallet-locations.csv.
to string required
New name for the wallet. Cannot be empty and must not already exist in the same location.

Response

Returns a JSON object with the rename operation result.

Success Response Properties

status string
Always "success" for successful rename.
operation string
Always "wallet-rename".
from string
The original wallet name.
to string
The new wallet name.
location string
The filesystem path where the wallet is located (unchanged).
message string
Human-readable success message.

Success Response Example

{
  "status": "success",
  "operation": "wallet-rename",
  "from": "OldName",
  "to": "NewName",
  "location": "C:\\MyWallet3",
  "message": "Wallet renamed successfully"
}

Error Response Properties

error string
Human-readable error message.
status_code integer
HTTP status code (400, 404, 409, or 500).

Error Response Examples

// 400 Bad Request - Missing parameter
{
  "error": "Missing 'from' or 'to' parameter",
  "status_code": 400
}

// 400 Bad Request - Empty name
{
  "error": "Wallet name cannot be empty",
  "status_code": 400
}

// 400 Bad Request - Already same name
{
  "error": "Wallet already has this name",
  "status_code": 400
}

// 404 Not Found - Wallet doesn't exist
{
  "error": "Wallet not found",
  "status_code": 404
}

// 409 Conflict - Name already exists
{
  "error": "A wallet with the new name already exists",
  "status_code": 409
}

// 500 Internal Server Error - Filesystem error
{
  "error": "Failed to rename wallet directory",
  "status_code": 500
}

// 500 Internal Server Error - Config save error
{
  "error": "Failed to save wallet configuration",
  "status_code": 500
}

Examples

JavaScript (fetch)

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

async function renameWallet(fromName, toName) {
    try {
        const url = `${API_HOST}/api/wallet/rename?from=${encodeURIComponent(fromName)}&to=${encodeURIComponent(toName)}`;
        const response = await fetch(url);
        const result = await response.json();

        if (response.ok) {
            console.log('Wallet renamed successfully:');
            console.log(`From: ${result.from}`);
            console.log(`To: ${result.to}`);
            console.log(`Location: ${result.location}`);
        } else {
            console.error('Error:', result.error);
        }
    } catch (error) {
        console.error('Request failed:', error);
    }
}

// Example: Rename "OldWallet" to "ProductionWallet"
renameWallet('OldWallet', 'ProductionWallet');

cURL

# Rename wallet from "OldWallet" to "ProductionWallet"
curl -X GET "http://localhost:8080/api/wallet/rename?from=OldWallet&to=ProductionWallet"

# With URL encoding for spaces
curl -X GET "http://localhost:8080/api/wallet/rename?from=My%20Wallet&to=My%20New%20Wallet"

Go

package main

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

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

type RenameResponse struct {
    Status    string `json:"status"`
    Operation string `json:"operation"`
    From      string `json:"from"`
    To        string `json:"to"`
    Location  string `json:"location"`
    Message   string `json:"message"`
}

type ErrorResponse struct {
    Error      string `json:"error"`
    StatusCode int    `json:"status_code"`
}

func renameWallet(fromName, toName string) error {
    // Build URL with query parameters
    baseURL := fmt.Sprintf("%s/api/wallet/rename", ApiHost)
    params := url.Values{}
    params.Add("from", fromName)
    params.Add("to", toName)

    fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())

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

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

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

        fmt.Printf("Success: %s\n", result.Message)
        fmt.Printf("From: %s\n", result.From)
        fmt.Printf("To: %s\n", result.To)
        fmt.Printf("Location: %s\n", result.Location)
        return nil
    }

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

    return fmt.Errorf("API error (%d): %s", resp.StatusCode, errResult.Error)
}

func main() {
    if err := renameWallet("OldWallet", "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 'from' and 'to' parameters must be provided
  2. Empty Name Check: New name cannot be empty string
  3. Wallet Exists: Wallet with 'from' name must exist in wallet-locations.csv
  4. Same Name Check: Returns error if wallet already has the target name
  5. Conflict Check: No wallet with 'to' name can exist in same location
  6. Filesystem Check: Directory must exist before rename attempt
  7. Rename Operation: Filesystem rename must succeed
  8. Config Save: Updated configuration must save successfully

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"), 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
  • The wallet-locations.csv still has the old name
  • Manual correction may be required (rename directory back or edit config)
  • Check file permissions on wallet-locations.csv
💡 Location Preservation

The rename operation only changes the wallet name, not its location:

  • The wallet's filesystem path remains the same except for the directory name
  • All coins and subfolders (Bank, Fracked, etc.) are preserved
  • Only the final directory name changes
  • Example: C:\MyWallet3\OldNameC:\MyWallet3\NewName
🔍 Platform Differences

The endpoint handles platform-specific filesystem operations:

  • Windows: Uses _access() for existence check and rename()
  • Unix/Linux: Uses stat() for existence check and rename()
  • Both platforms use standard C rename() function
  • Path separators automatically adjusted per platform

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.