/api/wallet/create

GET

Creates a new wallet at the active wallet's location with all necessary folder structure.

http://localhost:8080/api/wallet/create?name={wallet_name}

Description

The `/api/wallet/create` endpoint creates a new wallet in the currently active wallet location. It automatically creates all required subdirectories (Bank, Fracked, Counterfeit, Limbo, Import, Export, Receipts, etc.), adds the wallet to the configuration file, and sets it as the active wallet.

⚠️ Automatic Activation

The newly created wallet automatically becomes the active wallet. All subsequent coin operations will use this wallet until you switch to a different one.

💡 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 Location

The new wallet is created in the same parent directory as the currently active wallet. For example, if the active wallet is at C:\MyWallet3\Default, a new wallet named "Savings" would be created at C:\MyWallet3\Savings.

Parameters

Parameter	Type	Required	Description
`name`	string	Yes	The name for the new wallet. Must not already exist at the active location.

Directory Structure Created

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

[location_path]/[wallet_name]/
├── Bank/              # Authenticated coins (13+ RAIDA passes)
├── Fracked/           # Partially authenticated coins (< 13 passes)
├── Counterfeit/       # Rejected coins (authentication failed)
├── Limbo/             # Coins with uncertain status
├── Corrupted/         # Damaged or malformed coin files
├── Duplicates/        # Duplicate coin detection
├── Encryption_Failed/ # Coins that failed encryption/decryption
├── Errored/           # Coins with processing errors
├── Export/            # Coins prepared for export/transfer
├── Grade/             # Coins ready for grading/sorting
├── Import/            # Incoming coins to be processed
├── Imported/          # Successfully imported coins (archive)
├── Lockered/          # Coins stored in RAIDA locker
├── Pending/           # Coins being processed
├── Receipts/          # Transaction receipts and logs
├── Sent/              # Coins that have been sent
├── Suspect/           # Coins needing authentication
├── Trash/             # Deleted coins (recoverable)
├── Withdrawn/         # Coins withdrawn from locker
└── transactions.csv   # Transaction history ledger

📁 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

status string

Always "success" if the request was processed.

operation string

The operation type - "wallet-create".

wallet string

The name of the newly created wallet.

location string

The parent directory path where the wallet was created.

path string

The full path to the new wallet directory.

message string

A confirmation message.

Example Response (Success)

{
  "status": "success",
  "operation": "wallet-create",
  "wallet": "Savings",
  "location": "C:\\Users\\User\\MyWallet3",
  "path": "C:\\Users\\User\\MyWallet3\\Savings",
  "message": "Wallet created successfully and set as active"
}

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(walletName) {
    try {
        const response = await fetch(`${API_HOST}/api/wallet/create?name=${encodeURIComponent(walletName)}`);
        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);

            // Optional: Switch to the new wallet
            // await switchWallet(result.wallet);
        } else {
            console.error('Failed to create wallet:', result.error);
        }
    } catch (error) {
        console.error('Error creating wallet:', error);
    }
}

// Example: Create "Savings" wallet
createWallet('Savings');

cURL

# Create a new wallet named "Savings"
curl -X GET "http://localhost:8080/api/wallet/create?name=Savings"

# Create a wallet with a multi-word name
curl -X GET "http://localhost:8080/api/wallet/create?name=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(walletName string) error {
    // Properly encode the wallet name for URL
    params := url.Values{}
    params.Add("name", walletName)

    requestURL := fmt.Sprintf("%s/api/wallet/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 "Savings" wallet
    if err := createWallet("Savings"); err != nil {
        fmt.Printf("Error: %v\n", err)
    }
}

Behavior Details

Wallet Creation Process

Validation: Checks that wallet name is provided and no wallet with the same name exists in the active location
Directory Creation: Creates the main wallet directory at [location]/[name]
Subdirectory Creation: Creates all 19 required subdirectories (Bank, Fracked, etc.)
Transaction File: Initializes transactions.csv with CSV header
Configuration Update: Adds wallet to wallet-locations.csv
Activation: Sets the new wallet as the active wallet (moved to index 0)
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 'name' parameter	The `name` 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.

View Details

/api/wallet/switch

Switch between different wallets to change which one is active.

View Details

/api/coins/import

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

View Details

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/wallet/create?name=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();