/wallets/{name}

GET PUT DELETE SYNC

Retrieve, update (rename), or delete a specific wallet by its name.

GET /api/v1//wallets/{name}

Alias: /get-wallet/{name}

PUT /api/v1//wallets/{name}

Alias: /update-wallet/{name}

DELETE /api/v1//wallets/{name}

Alias: /delete-wallet/{name}

Description

This endpoint allows you to interact with a single wallet, which is identified by its `name` provided in the URL path. You can retrieve its details (`GET`), change its name (`PUT`), or permanently delete it (`DELETE`). All actions are synchronous and return a response immediately.

Path Parameters

Parameter	Type	Required	Description
`name`	string	Yes	The URL-encoded name of the wallet to retrieve, update, or delete.

GET /wallets/{name}

Returns detailed information about the specified wallet, including its balance, denomination breakdown, and transaction history.

Response Body

Wallet Object Properties

namestring

The unique name of the wallet.

balanceinteger

Total balance of the wallet in CloudCoin units.

denominationsobject

Breakdown of coin counts by their denomination value.

transactionsarray

An array of transaction objects for the wallet.

amount_statsobject

A summary of the wallet's balance by coin status (e.g., "Bank", "Fracked").

Example Response Body

{
    "name": "Default",
    "balance": 12500,
    "denominations": {
        "1": 10000,
        "250": 10
    },
    "transactions": [
        {
            "amount": 12500,
            "message": "Receive",
            "type": "GetFromLocker",
            "datetime": "2025-07-09T11:45:00+05:30",
            "receiptid": "f3e1d60e2461e8c5832ca9f0a617a988",
            "running_balance": 12500,
            "negative": false
        }
    ],
    "amount_stats": {
        "Bank": 12500
    }
}

PUT /wallets/{name}

Changes the name of an existing wallet.

Request Body

Parameter	Type	Required	Description
`new_name`	string	Yes	The new, unique name for the wallet.

Example Request Body

{
    "new_name": "Primary"
}

Response

Returns a `200 OK` on a successful rename. Returns an error if the new name is already in use.

DELETE /wallets/{name}

Permanently deletes the specified wallet and all its contents.

Response

Returns a `200 OK` if the wallet was successfully deleted. If the wallet does not exist, it returns a `404 Not Found` error.

⚠️ This action is permanent

Deleting a wallet removes all its coins and transaction history and cannot be undone. Always back up your wallet before performing this action.

Examples

JavaScript: Get a Wallet

async function getWallet(walletName) {
    const response = await fetch(`http://localhost:8006/api/v1/wallets/${walletName}`);
    const wallet = await response.json();
    console.log(`Details for ${walletName}:`, wallet);
}

JavaScript: Rename a Wallet

async function renameWallet(oldName, newName) {
    await fetch(`http://localhost:8006/api/v1/wallets/${oldName}`, {
        method: 'PUT',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ new_name: newName })
    });
    console.log(`Wallet '${oldName}' renamed to '${newName}'.`);
}

JavaScript: Delete a Wallet

async function deleteWallet(walletName) {
    if (confirm(`Are you sure you want to delete '${walletName}'?`)) {
        await fetch(`http://localhost:8006/api/v1/wallets/${walletName}`, { method: 'DELETE' });
        console.log(`Wallet '${walletName}' deleted.`);
    }
}

cURL: Get a Wallet

# Get details for the "Default" wallet
curl -X GET "http://localhost:8006/api/v1/wallets/Default"

cURL: Rename a Wallet

# Rename the "Default" wallet to "Primary"
curl -X PUT "http://localhost:8006/api/v1/wallets/Default" \
-H "Content-Type: application/json" -d '{"new_name": "Primary"}'

cURL: Delete a Wallet

# Delete the "Primary" wallet
curl -X DELETE "http://localhost:8006/api/v1/wallets/Primary"

Go: Get a Wallet

package main
import ("encoding/json"; "fmt"; "net/http")

type Wallet struct {
    Name    string `json:"name"`
    Balance int64  `json:"balance"`
}

func getWallet(name string) {
    resp, err := http.Get(fmt.Sprintf("http://localhost:8006/api/v1/wallets/%s", name))
    if err != nil { panic(err) }
    defer resp.Body.Close()

    var wallet Wallet
    if err := json.NewDecoder(resp.Body).Decode(&wallet); err != nil {
        panic(err)
    }
    fmt.Printf("Fetched wallet: %+v\n", wallet)
}

Go: Rename a Wallet

package main
import ("bytes"; "encoding/json"; "fmt"; "net/http")

func renameWallet(oldName, newName string) {
    payload, _ := json.Marshal(map[string]string{"new_name": newName})
    req, _ := http.NewRequest(http.MethodPut, fmt.Sprintf("http://localhost:8006/api/v1/wallets/%s", oldName), bytes.NewBuffer(payload))
    req.Header.Set("Content-Type", "application/json")
    
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    if resp.StatusCode == http.StatusOK {
        fmt.Printf("Wallet '%s' successfully renamed to '%s'.\n", oldName, newName)
    } else {
        fmt.Printf("Failed to rename wallet. Status: %s\n", resp.Status)
    }
}

Go: Delete a Wallet

package main
import ("fmt"; "net/http")

func deleteWallet(name string) {
    req, _ := http.NewRequest(http.MethodDelete, fmt.Sprintf("http://localhost:8006/api/v1/wallets/%s", name), nil)
    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    if resp.StatusCode == http.StatusOK {
        fmt.Printf("Wallet '%s' successfully deleted.\n", name)
    } else {
        fmt.Printf("Failed to delete wallet. Status: %s\n", resp.Status)
    }
}