CloudCoin > API Reference > /wallets

/wallets

GET POST SYNC

Lists all local wallets or creates a new one.

GET /api/v1/wallets
Alias: /list-all-wallets
POST /api/v1/wallets
Alias: /create-wallet

Description

This endpoint is the primary tool for managing wallets. A `GET` request retrieves a list of all existing wallets and their contents, while a `POST` request creates a new, empty wallet. All calls to this endpoint are synchronous and return immediately.

GET /wallets

To retrieve a detailed list of all wallets, make a `GET` request to this endpoint. This is useful for displaying wallet balances and transaction histories in a user interface.

Response Body: GET /wallets

Returns a `200 OK` with a JSON array, where each element is a full Wallet object.

Wallet Object Properties

namestring
The unique name of the wallet.
balanceinteger
Total balance of the wallet in CloudCoin units.
denominationsobject
A 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-08T17:22:00+05:30",
                "receiptid": "f3e1d60e2461e8c5832ca9f0a617a988",
                "running_balance": 12500,
                "negative": false
            }
        ],
        "amount_stats": { "Bank": 12500 }
    },
    {
        "name": "MySavings",
        "balance": 0,
        "denominations": {},
        "transactions": [],
        "amount_stats": {}
    }
]

POST /wallets

To create a new, empty wallet, make a `POST` request with the wallet's desired name and optional credentials.

Request Body: POST /wallets

ParameterTypeRequiredDescription
name string Yes A unique name for the new wallet.
email string No An optional email address to associate with the wallet.
password string No An optional password to encrypt the wallet.

Example Request Body

{
  "name": "MyNewWallet",
  "email": "[email protected]"
}

Response: POST /wallets

Returns a `200 OK` with an empty body on success. If the wallet name already exists, it returns a `400 Bad Request` with an error message.

Example Error Response Body

{
    "status": "error",
    "error": {
        "code": "wallet_exists",
        "message": "Wallet with the same name already exists"
    }
}

Examples

JavaScript: GET Wallets

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

async function listWallets() {
    const response = await fetch(`${API_HOST}/api/v1/wallets`);
    const wallets = await response.json();
    console.log("Available Wallets:", wallets);
}

listWallets();

JavaScript: Create New Wallet

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

async function createWallet(walletName) {
    const response = await fetch(`${API_HOST}/api/v1/wallets`, {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ name: walletName })
    });
    if (response.ok) {
        console.log(`Wallet '${walletName}' created successfully.`);
    } else {
        const err = await response.json();
        console.error(`Failed to create wallet:`, err.error.message);
    }
}

createWallet("MyNewWallet");

cURL: GET Wallets

# Get a list of all wallets
curl -X GET "http://localhost:8006/api/v1/wallets"

cURL: Create New Wallet

# Create a new wallet named "Trading"
curl -X POST "http://localhost:8006/api/v1/wallets" \
-H "Content-Type: application/json" \
-d '{"name": "Trading"}'

Go: List Wallets

package main

import (
    "encoding/json"
    "fmt"
    "net/http"
)

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

func listWallets() {
    resp, err := http.Get("http://localhost:8006/api/v1/wallets")
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    var wallets []Wallet
    if err := json.NewDecoder(resp.Body).Decode(&wallets); err != nil {
        panic(err)
    }

    fmt.Println("Available Wallets:")
    for _, w := range wallets {
        fmt.Printf("- %s (Balance: %d)\n", w.Name, w.Balance)
    }
}

Go: Create New Wallet

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func createWallet(walletName string) {
    payload, _ := json.Marshal(map[string]string{"name": walletName})
    resp, err := http.Post(
        "http://localhost:8006/api/v1/wallets",
        "application/json",
        bytes.NewBuffer(payload),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

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