/api/wallets/create
GETCreates 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.
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.
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
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
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
- Validation: Checks that the wallet path is provided and no wallet already exists at the specified path
- Directory Creation: Creates the main wallet directory at the specified path
- Subdirectory Creation: Creates all 19 required subdirectories (Bank, Fracked, etc.)
- Transaction File: Initializes
transactions.csvwith 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
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
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();