/api/wallets/transactions

GET

Retrieve recent transaction history from the specified wallet's transactions.csv file.

Description

The `/api/wallets/transactions` endpoint returns the most recent transaction history from a specified wallet by providing the wallet_path parameter.

Transactions are automatically recorded in the wallet's `transactions.csv` file whenever CloudCoin operations are performed (imports, exports, grade operations, etc.). The endpoint returns transactions in reverse chronological order (most recent first) and supports pagination through the `limit` parameter. Each transaction includes details such as date, time, task ID, deposit/withdraw amounts, running balance, and description.

💡 Use Case

This endpoint is perfect for:

  • Displaying transaction history in wallet interfaces
  • Auditing wallet activity and balance changes
  • Tracking deposits and withdrawals over time
  • Linking to detailed transaction receipts via task IDs
  • Monitoring wallet activity for security purposes
  • Accessing transactions from any wallet directly by path

Parameters

This endpoint requires the wallet path parameter and accepts optional query parameters to control the number of transactions returned.

Query Parameters

wallet_path string required
Absolute path to the wallet directory to retrieve transactions from.
  • Format: Absolute file system path (e.g., E:\Data\Wallets\Default on Windows or /home/user/CloudCoin/Wallets/Default on Linux/macOS)
  • Path Validation: Must point to a valid wallet directory with a Data/transactions.csv file
limit integer optional
Number of recent transactions to return.
  • Minimum: 1
  • Default: 10
  • Maximum: 100

Response

Returns a JSON object containing the transaction history array and metadata.

Response Properties

command string
Always "wallet-transactions".
success boolean
Always true for successful requests.
wallet_path string
Full filesystem path to the wallet.
wallet_name string
Wallet display name (extracted from path).
count integer
Number of transactions returned (0 if no transactions exist).
transactions array
Array of transaction objects, sorted by most recent first.

Transaction Object Properties

date string
Transaction date in format "YYYY-MM-DD".
time string
Transaction time in format "HH:MM:SS".
symbol string
UTF-8 transaction symbol (arrows indicating direction: 🡆 for deposits/transfers in, 🡄 for withdrawals/transfers out, 🡇 for locker downloads, 🡅 for locker uploads, ⚠️ for adjustments).
type string
Human-readable transaction type: "Import", "Withdraw", "From Locker", "To Locker", "Transferred In", "Transferred Out", or "Adjustment".
task_id string
Unique task identifier (e.g., "Jan-31-25_03-30-45-PM"). Can be used to retrieve detailed receipt files.
remarks string
Transaction type (Import, Grade, Export, etc.).
deposit string
Deposit amount (empty string if no deposit).
withdraw string
Withdrawal amount (empty string if no withdrawal).
balance string
Running balance after this transaction.
description string
Human-readable description of the transaction.

Example Response (With Transactions)

{
  "status": "success",
  "operation": "wallet-transactions",
  "wallet": "Default",
  "count": 2,
  "transactions": [
    {
      "date": "2025-01-31",
      "time": "15:45:12",
      "symbol": "🡄",
      "type": "Withdraw",
      "task_id": "Jan-31-25_03-45-12-PM",
      "remarks": "Grade",
      "deposit": "",
      "withdraw": "100.00",
      "balance": "5150.00",
      "description": "Graded coins to Bank"
    },
    {
      "date": "2025-01-31",
      "time": "15:30:45",
      "symbol": "🡆",
      "type": "Import",
      "task_id": "Jan-31-25_03-30-45-PM",
      "remarks": "Import",
      "deposit": "250.00",
      "withdraw": "",
      "balance": "5250.00",
      "description": "Imported 1 coin"
    }
  ]
}

Example Response (No Transactions)

{
  "status": "success",
  "operation": "wallet-transactions",
  "wallet": "Default",
  "count": 0,
  "transactions": []
}

Error Responses

The endpoint may return the following error responses:

No Active Wallet (400 Bad Request)

{
  "status": "error",
  "operation": "wallet-transactions",
  "error_code": 400,
  "message": "No active wallet"
}

Transaction File Details

The endpoint reads from the transactions.csv file stored in the wallet's Data directory. This file is automatically created and updated by CloudCoin operations.

📁 File Location

[wallet]/Data/transactions.csv

CSV File Format

date,time,symbol,task_id,remarks,deposit,withdraw,balance,description
2025-01-31,15:30:45,CC,Jan-31-25_03-30-45-PM,Import,250.00,,5250.00,Imported 1 coin
2025-01-31,15:45:12,CC,Jan-31-25_03-45-12-PM,Grade,,100.00,5150.00,Graded coins to Bank
🔗 Task ID Linking

Each transaction's task_id corresponds to a detailed receipt file in the wallet's Receipts folder. Receipt files follow the naming pattern:

[task_id].[transaction-type].txt

For example: Jan-31-25_03-30-45-PM.Import.txt

Use the /api/wallet/receipt endpoint to retrieve these detailed receipt files.

Examples

JavaScript (fetch)

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

// Get wallet transactions by path
async function getWalletTransactions(walletPath, limit = 10) {
    try {
        const url = `${API_HOST}/api/wallets/transactions?wallet_path=${encodeURIComponent(walletPath)}&limit=${limit}`;
        const response = await fetch(url);
        const result = await response.json();

        if (result.status === 'success') {
            console.log(`Wallet: ${result.wallet}`);
            console.log(`Transaction Count: ${result.count}`);
            console.log('\nRecent Transactions:');

            result.transactions.forEach((tx, index) => {
                console.log(`\n${index + 1}. ${tx.date} ${tx.time}`);
                console.log(`   Task: ${tx.task_id}`);
                console.log(`   Type: ${tx.remarks}`);
                if (tx.deposit) {
                    console.log(`   Deposit: +${tx.deposit}`);
                }
                if (tx.withdraw) {
                    console.log(`   Withdraw: -${tx.withdraw}`);
                }
                console.log(`   Balance: ${tx.balance}`);
                console.log(`   ${tx.description}`);
            });
        } else {
            console.error('Error:', result.message);
        }
    } catch (error) {
        console.error('Error fetching transactions:', error);
    }
}

// Get last 10 transactions from wallet
getWalletTransactions('C:\\CloudCoin\\Pro\\Wallets\\Default', 10);

// Get last 25 transactions from specific wallet
getWalletTransactions('C:\\CloudCoin\\Pro\\Wallets\\MyWallet', 25);

cURL

# Get last 10 transactions from wallet (default limit) - Windows
curl -X GET "http://localhost:8080/api/wallets/transactions?wallet_path=E:\Data\Wallets\Default"

# Get last 25 transactions from wallet
curl -X GET "http://localhost:8080/api/wallets/transactions?wallet_path=E:\Data\Wallets\Default&limit=25"

# Get maximum allowed transactions (100)
curl -X GET "http://localhost:8080/api/wallets/transactions?wallet_path=E:\Data\Wallets\Default&limit=100"

# Get transactions from wallet path on Linux/macOS
curl -X GET "http://localhost:8080/api/wallets/transactions?wallet_path=/home/user/CloudCoin/Wallets/Default&limit=10"

# Pretty print JSON output
curl -X GET "http://localhost:8080/api/wallets/transactions?wallet_path=E:\Data\Wallets\Default&limit=10" | json_pp

Go

package main

import (
    "encoding/json"
    "fmt"
    "io/ioutil"
    "net/http"
    "net/url"
)

const ApiHost = "http://localhost:8080"

type Transaction struct {
    Date        string `json:"date"`
    Time        string `json:"time"`
    Symbol      string `json:"symbol"`
    Type        string `json:"type"`
    TaskID      string `json:"task_id"`
    Remarks     string `json:"remarks"`
    Deposit     string `json:"deposit"`
    Withdraw    string `json:"withdraw"`
    Balance     string `json:"balance"`
    Description string `json:"description"`
}

type TransactionsResponse struct {
    Status       string        `json:"status"`
    Operation    string        `json:"operation"`
    Wallet       string        `json:"wallet"`
    Count        int           `json:"count"`
    Transactions []Transaction `json:"transactions"`
}

// Get transactions from wallet by path
func GetWalletTransactions(walletPath string, limit int) (*TransactionsResponse, error) {
    params := url.Values{}
    params.Add("wallet_path", walletPath)
    params.Add("limit", fmt.Sprintf("%d", limit))

    fullUrl := fmt.Sprintf("%s/api/wallets/transactions?%s", ApiHost, params.Encode())
    resp, err := http.Get(fullUrl)
    if err != nil {
        return nil, err
    }
    defer resp.Body.Close()

    body, err := ioutil.ReadAll(resp.Body)
    if err != nil {
        return nil, err
    }

    var result TransactionsResponse
    if err := json.Unmarshal(body, &result); err != nil {
        return nil, err
    }

    return &result, nil
}

func PrintTransactions(result *TransactionsResponse) {
    fmt.Printf("Wallet: %s\n", result.Wallet)
    fmt.Printf("Transaction Count: %d\n\n", result.Count)

    for i, tx := range result.Transactions {
        fmt.Printf("%d. %s %s\n", i+1, tx.Date, tx.Time)
        fmt.Printf("   Task: %s\n", tx.TaskID)
        fmt.Printf("   Type: %s\n", tx.Remarks)
        if tx.Deposit != "" {
            fmt.Printf("   Deposit: +%s\n", tx.Deposit)
        }
        if tx.Withdraw != "" {
            fmt.Printf("   Withdraw: -%s\n", tx.Withdraw)
        }
        fmt.Printf("   Balance: %s\n", tx.Balance)
        fmt.Printf("   %s\n\n", tx.Description)
    }
}

func main() {
    // Get transactions from wallet
    walletPath := "C:\\CloudCoin\\Pro\\Wallets\\Default"
    result, err := GetWalletTransactions(walletPath, 10)
    if err != nil {
        panic(err)
    }
    fmt.Println("=== Wallet Transactions ===")
    PrintTransactions(result)

    // Get transactions from another wallet
    walletPath2 := "C:\\CloudCoin\\Pro\\Wallets\\MyWallet"
    result2, err := GetWalletTransactions(walletPath2, 10)
    if err != nil {
        panic(err)
    }
    fmt.Println("\n=== Another Wallet Transactions ===")
    PrintTransactions(result2)
}

Implementation Details

🎯 Wallet Path Required

The endpoint requires the wallet_path parameter:

  • Path format: Uses the specified absolute path to access transactions directly from that wallet
  • Path resolution: Translates the wallet path to [wallet_path]/Data/transactions.csv
  • Validation: Verifies the wallet directory exists and contains required data files
📊 Transaction Ordering

Transactions are returned in reverse chronological order (most recent first). The endpoint:

  1. Reads all transactions from the CSV file (up to 1000 entries)
  2. Stores them in memory
  3. Returns the last N transactions based on the limit parameter

This ensures the most recent transactions are always at the beginning of the array.

⚡ Performance Considerations
  • Maximum limit of 100 transactions prevents excessive memory usage
  • Internal limit of 1000 total transactions read from file
  • Empty files return immediately with count=0 (no error)
  • Missing transactions.csv file is treated as success with empty array
⚠️ Path Validation

When using wallet_path, the endpoint validates:

  • Path is not empty and not null
  • Wallet directory exists at the specified location
  • Data directory exists within the wallet
  • Returns appropriate error if any validation fails

Related Endpoints

/api/wallet/receipt

Retrieve detailed receipt files for specific transactions using their task IDs.

/api/wallet/balance

Get the current balance of the active wallet across all folders (Bank, Fracked, etc.).

/api/wallet/show-coins

View detailed information about coins in specific wallet folders.