/wallets
GET POST SYNCCreate 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