/api/wallets/create

GET

Creates a new wallet at a specified path with all necessary folder structure.

Description

The `/api/wallets/create` endpoint creates a new wallet at the specified path. It automatically creates all required subdirectories (Bank, Fracked, Counterfeit, Limbo, Import, Export, Receipts, etc.) and adds the wallet to the configuration file.

šŸ’” Directory Structure

Creating a wallet automatically generates 19 subdirectories including Bank, Fracked, Counterfeit, Limbo, Import, Export, Receipts, and more. This ensures the wallet is immediately ready for coin operations.

šŸ’” Wallet Path

The wallet is created at the exact path you specify. For example, C:\CloudCoin\Wallets\Savings will create a new wallet named "Savings" in the C:\CloudCoin\Wallets directory.

Parameters

Parameter Type Required Description
wallet_path string Yes The full file system path where the wallet will be created (e.g., E:/Data/Wallets/Default or /home/user/CloudCoin/Wallets/Savings). The wallet name is derived from the last component of the path.

Directory Structure Created

When you create a wallet, the following directory structure is automatically generated:

[location_path]/[wallet_name]/
ā”œā”€ā”€ Bank/              # Authenticated coins (passed 13+ RAIDAs)
ā”œā”€ā”€ BillPay/           # Instructions to the wallet about automatic payments
ā”œā”€ā”€ Corrupted/         # Files that couldn't be parsed
ā”œā”€ā”€ Counterfeit/       # Rejected coins (failed authentication)
ā”œā”€ā”€ Duplicates/        # Duplicate serial numbers detected
ā”œā”€ā”€ EmailIn/           # Coins received by email but not processed yet
ā”œā”€ā”€ EmailOut/          # Coins sent by email
ā”œā”€ā”€ Encryption_Failed/ # Coins that failed encryption/decryption
ā”œā”€ā”€ Errored/           # Coins that encountered errors during processing
ā”œā”€ā”€ Export/            # Staging area for coins being exported
ā”œā”€ā”€ Exported/          # Coin files that were removed from the wallet
ā”œā”€ā”€ Fracked/           # Partially failed coins (need healing)
ā”œā”€ā”€ Gallery/           # Pictures or files associated with coins (NFTs)
ā”œā”€ā”€ Grade/             # Staging area for grading operations
ā”œā”€ā”€ Import/            # Incoming coin files to be processed
ā”œā”€ā”€ Imported/          # Successfully imported coins (archive)
ā”œā”€ā”€ Limbo/             # Uncertain status coins
ā”œā”€ā”€ Lockered/          # Coins stored in RAIDA locker
ā”œā”€ā”€ Logs/              # Logs specific to this wallet
ā”œā”€ā”€ Mind/              # Coins that were made for the person to remember
ā”œā”€ā”€ PayForward/        # Coins reserved for bill pay
ā”œā”€ā”€ Payments/          # For future use
ā”œā”€ā”€ Pending/           # Operations in progress
ā”œā”€ā”€ Receipts/          # Transaction logs and receipts
ā”œā”€ā”€ Requests/          # Requests from people who want payments
ā”œā”€ā”€ RequestResponses/  # Responses to payment requests
ā”œā”€ā”€ Sent/              # Coins that have been sent
ā”œā”€ā”€ Suspect/           # Suspicious coins requiring investigation
ā”œā”€ā”€ Temp/              # Place that coins can be stored temporarily if needed
ā”œā”€ā”€ Trash/             # Deleted coins
ā”œā”€ā”€ TrustedTransfer/   # Coins sent to banks
ā”œā”€ā”€ Vault/             # Files that need to be encrypted by the user's password
└── Withdrawn/         # Coins withdrawn from system
šŸ“ Folder Purposes

Each folder serves a specific purpose in the coin lifecycle:

  • Bank: Your authenticated, spendable coins
  • Fracked: Coins that need healing (use Fix command)
  • Import: Drop new coin files here to import them
  • Export: Coins prepared for sending to others
  • Receipts: Detailed logs of all wallet operations

Response

Returns a JSON object with information about the newly created wallet.

Response Properties

command string
Always "wallet-create".
success boolean
Always true if the wallet was created successfully.
wallet_name string
The name of the newly created wallet (extracted from path).
wallet_path string
The full filesystem path to the new wallet directory.
message string
Confirmation message - "Wallet created successfully".

Example Response (Success)

{
  "command": "wallet-create",
  "success": true,
  "wallet_name": "TestWallet",
  "wallet_path": "E:\\Data\\Wallets\\TestWallet",
  "message": "Wallet created successfully"
}

Example Error Response (Missing Parameter)

{
  "error": "Missing 'name' parameter"
}

Example Error Response (Wallet Exists)

{
  "error": "Wallet already exists in this location"
}

Examples

JavaScript (fetch)

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

async function createWallet(walletPath) {
    try {
        const encodedPath = encodeURIComponent(walletPath);
        const response = await fetch(`${API_HOST}/api/wallets/create?wallet_path=${encodedPath}`);
        const result = await response.json();

        if (result.status === 'success') {
            console.log(`Created wallet: ${result.wallet}`);
            console.log(`Location: ${result.location}`);
            console.log(`Full path: ${result.path}`);
            console.log(result.message);
        } else {
            console.error('Failed to create wallet:', result.error);
        }
    } catch (error) {
        console.error('Error creating wallet:', error);
    }
}

// Example: Create wallet at specific path
createWallet('E:/Data/Wallets/Default');

cURL

# Create a new wallet at a specific path
curl -X GET "http://localhost:8080/api/wallets/create?wallet_path=E:/Data/Wallets/Default"

# Create a wallet with spaces in the path
curl -X GET "http://localhost:8080/api/wallets/create?wallet_path=E:/Data/Wallets/My%20Backup%20Wallet"

Go

package main

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

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

type WalletCreateResponse struct {
    Status    string `json:"status"`
    Operation string `json:"operation"`
    Wallet    string `json:"wallet"`
    Location  string `json:"location"`
    Path      string `json:"path"`
    Message   string `json:"message"`
}

func createWallet(walletPath string) error {
    // Properly encode the wallet path for URL
    params := url.Values{}
    params.Add("wallet_path", walletPath)

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

    resp, err := http.Get(requestURL)
    if err != nil {
        return err
    }
    defer resp.Body.Close()

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

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

    if result.Status == "success" {
        fmt.Printf("Created wallet: %s\n", result.Wallet)
        fmt.Printf("Location: %s\n", result.Location)
        fmt.Printf("Full path: %s\n", result.Path)
        fmt.Println(result.Message)
    } else {
        return fmt.Errorf("wallet creation failed")
    }

    return nil
}

func main() {
    // Example: Create wallet at specific path
    if err := createWallet("E:/Data/Wallets/Default"); err != nil {
        fmt.Printf("Error: %v\n", err)
    }
}

Behavior Details

Wallet Creation Process

  1. Validation: Checks that the wallet path is provided and no wallet already exists at the specified path
  2. Directory Creation: Creates the main wallet directory at the specified path
  3. Subdirectory Creation: Creates all 19 required subdirectories (Bank, Fracked, etc.)
  4. Transaction File: Initializes transactions.csv with CSV header
  5. Configuration Update: Adds wallet to wallet-locations.csv
  6. Activation: Sets the new wallet as the active wallet (moved to index 0)
  7. Persistence: Saves configuration to disk

Location Inheritance

The new wallet inherits properties from the currently active location:

  • Location Path: Created in the same parent directory as the active wallet
  • USB Flag: Inherits USB storage detection setting
  • Network Flag: Inherits network storage detection setting
  • Auto-mount: Inherits automatic mounting preference
  • Read-only: Inherits read-only status
āš ļø Active Location Required

You must have at least one active wallet location before creating new wallets. If you receive "No active location configured" error, use /api/wallet/add-location first to create a wallet location.

Error Handling

HTTP Status Error Message Cause
400 Missing 'wallet_path' parameter The wallet_path query parameter was not provided
400 No active location configured No wallet locations exist. Use /api/wallet/add-location first
409 Wallet already exists in this location A wallet with this name already exists in the active location
500 Failed to create wallet structure: [details] Filesystem error creating directories (check permissions)
500 Failed to add wallet to config Error updating in-memory configuration
500 Failed to save wallet configuration Error writing wallet-locations.csv to disk

Related Endpoints

/api/wallet/list

View all configured wallets including the newly created one.

/api/wallet/switch

Switch between different wallets to change which one is active.

/api/coins/import

Import coin files into the newly created wallet's Import folder.

Complete Workflow Example

Here's a complete example showing how to create a wallet and start using it:

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

async function setupNewWallet() {
    try {
        // Step 1: Create the wallet
        console.log('Creating new wallet...');
        const createResp = await fetch(
            `${API_HOST}/api/wallets/create?wallet_path=E:/Data/Wallets/Business`
        );
        const createResult = await createResp.json();

        if (createResult.status !== 'success') {
            throw new Error(createResult.error);
        }

        console.log(`āœ“ Wallet created: ${createResult.wallet}`);
        console.log(`  Path: ${createResult.path}`);

        // Step 2: Verify it's active
        const listResp = await fetch(`${API_HOST}/api/wallet/list`);
        const listResult = await listResp.json();

        const activeWallet = listResult.locations[0]?.wallets[0];
        console.log(`āœ“ Active wallet: ${activeWallet?.name}`);

        // Step 3: Check initial balance (should be 0)
        const balanceResp = await fetch(`${API_HOST}/api/wallet/balance`);
        const balanceResult = await balanceResp.json();

        console.log(`āœ“ Initial balance: ${balanceResult.total_value} CC`);
        console.log(`  Total coins: ${balanceResult.total_coins}`);

        // Step 4: Ready to import coins
        console.log(`\nāœ“ Wallet is ready!`);
        console.log(`  You can now import coins to: ${createResult.path}/Import/`);

    } catch (error) {
        console.error('Setup failed:', error.message);
    }
}

setupNewWallet();