/wallets

GET POST SYNC

Create and manage local CloudCoin wallets.

GET/POST /api/v1/wallets

Description

This endpoint allows you to retrieve a list of all local wallets (GET) or create a new wallet (POST). Wallets are used to store and manage CloudCoins locally on your device.

Note

This is a synchronous API call that returns results immediately, without creating a task.

GET /wallets

Returns a list of all local wallets with their details including balance, denomination breakdown, and transaction history.

Parameters

This endpoint does not require any parameters.

Response

Returns a 200 OK response with a JSON array containing details about all local wallets.

Response Properties (Wallet Object)

name string
The name of the wallet.
email string
Email associated with the wallet (if any).
password_hash string
Hashed password for the wallet (if password-protected).
balance integer
Total balance of the wallet in CloudCoin units.
denominations object
Breakdown of coin denominations in the wallet, where keys are denomination IDs and values are coin counts.
transactions array
Array of transaction objects representing the wallet's transaction history.
amount_stats object
Summary of wallet balances by category (e.g., "Bank").

Transaction Object Properties

amount integer
The amount of CloudCoins involved in the transaction.
message string
Description of the transaction.
type string
Transaction type (e.g., "GetFromLocker", "PutToLocker", "Created", "Adjustment").
datetime string
ISO 8601 timestamp of when the transaction occurred.
receiptid string
Unique identifier for the transaction receipt.
details object | null
Additional details about the transaction, if available.
running_balance integer
Wallet balance after this transaction.
negative boolean
Indicates whether the transaction decreased the wallet balance.

Example Response

[
  {
    "name": "Default",
    "email": "",
    "password_hash": "",
    "balance": 3000000020,
    "denominations": {
      "0": 0,
      "1": 3,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0,
      "6": 0,
      "248": 0,
      "249": 2,
      "250": 0,
      "251": 0,
      "252": 0,
      "253": 0,
      "254": 0,
      "255": 0
    },
    "transactions": [
      {
        "amount": 3000000020,
        "message": "Receive",
        "type": "GetFromLocker",
        "datetime": "2023-03-10T10:01:06+03:00",
        "receiptid": "f3e1d60e2461e8c5832ca9f0a617a988",
        "details": null,
        "running_balance": 3000000020,
        "negative": false
      },
      {
        "amount": 18446744070709551000,
        "message": "Balance Adjustment",
        "type": "Adjustment",
        "datetime": "2023-03-10T10:02:04+03:00",
        "receiptid": "-",
        "details": null,
        "running_balance": 0,
        "negative": false
      },
      {
        "amount": 3000000020,
        "message": "Receive",
        "type": "GetFromLocker",
        "datetime": "2023-03-10T10:06:06+03:00",
        "receiptid": "15f9ec58e329b8e3c48857faedb0662c",
        "details": null,
        "running_balance": 3000000020,
        "negative": false
      }
      // Additional transactions omitted for brevity
    ],
    "amount_stats": {
      "Bank": 3000000020
    }
  },
  {
    "name": "newWallet",
    "email": "",
    "password_hash": "",
    "balance": 0,
    "denominations": {
      "0": 0,
      "1": 0,
      "2": 0,
      "3": 0,
      "4": 0,
      "5": 0,
      "6": 0,
      "248": 0,
      "249": 0,
      "250": 0,
      "251": 0,
      "252": 0,
      "253": 0,
      "254": 0,
      "255": 0
    },
    "transactions": [],
    "amount_stats": {}
  }
]

POST /wallets

Creates a new local wallet. The wallet name must be unique.

Parameters

Request Body (JSON)

Parameter Type Required Description
name string Yes Name for the new wallet. Must be unique among all local wallets.

Example Request

{
  "name": "mywallet"
}

Response

Returns a 200 OK response if the wallet was created successfully.

Examples

JavaScript Example - GET Wallets

// Using Fetch API to get all wallets
const apiHost = 'http://localhost:8004';

fetch(`${apiHost}/api/v1/wallets`)
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! Status: ${response.status}`);
        }
        return response.json();
    })
    .then(wallets => {
        console.log('Wallets:', wallets);
        
        // Display wallet information
        wallets.forEach(wallet => {
            console.log(`Wallet: ${wallet.name}`);
            console.log(`Balance: ${wallet.balance}`);
            console.log(`Transactions: ${wallet.transactions.length}`);
            
            // Display denomination breakdown
            console.log('Denominations:');
            for (const [denom, count] of Object.entries(wallet.denominations)) {
                if (count > 0) {
                    console.log(`  Denomination ${denom}: ${count} coins`);
                }
            }
            
            console.log('-------------------');
        });
    })
    .catch(error => {
        console.error('Error fetching wallets:', error);
    });
    
// JavaScript Example - Create New Wallet
function createWallet(walletName) {
    fetch(`${apiHost}/api/v1/wallets`, {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json'
        },
        body: JSON.stringify({
            name: walletName
        })
    })
    .then(response => {
        if (!response.ok) {
            throw new Error(`HTTP error! Status: ${response.status}`);
        }
        console.log(`Wallet "${walletName}" created successfully!`);
    })
    .catch(error => {
        console.error('Error creating wallet:', error);
    });
}

// Call the function to create a new wallet
createWallet('new-test-wallet');

cURL Example - GET Wallets

# Get all wallets
curl -X GET "http://localhost:8004/api/v1/wallets" -H "accept: application/json"

# Example response (truncated for brevity):
# [{"name":"Default","email":"","password_hash":"","balance":3000000020,"denominations":{"0":0,"1":3,...},"transactions":[...],"amount_stats":{"Bank":3000000020}},{"name":"newWallet",...}]

cURL Example - Create New Wallet

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

# The response should be an empty 200 OK if successful