/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 accepts an optional wallet_path parameter and an optional limit parameter. If wallet_path is omitted, the Default wallet is used.

Query Parameters

wallet_path string optional
Absolute path to the wallet directory to retrieve transactions from.
  • Format: Absolute file system path (e.g., E:\Client_Data\Wallets\Default on Windows or E:/Client_Data/Wallets/Default on Linux/macOS)
  • Default: Uses the Default wallet if omitted
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 "transactions".
success boolean
Always true for successful requests.
wallet_path string
Not returned by the current implementation.
count integer
Number of transactions returned (0 if no transactions exist).
transactions array
Array of transaction objects. The current implementation returns each CSV line as a single raw string.

Transaction Object Properties

raw string
One raw CSV row from transactions.csv.

Example Response (With Transactions)

{
  "command": "transactions",
  "success": true,
  "count": 2,
  "transactions": [
    {
      "raw": "CC,Jan-31-25_03-45-12-PM,2025-01-31 15:45:12,Grade,,100.00,Graded coins to Bank,5150.00"
    },
    {
      "raw": "CC,Jan-31-25_03-30-45-PM,2025-01-31 15:30:45,Import,250.00,,Imported 1 coin,5250.00"
    }
  ]
}

Example Response (No Transactions)

{
  "command": "transactions",
  "success": true,
  "count": 0,
  "transactions": []
}

Error Responses

The endpoint may return the following error responses:

Wallet Not Found (404 Not Found)

{
  "error": true,
  "message": "Wallet not found",
  "code": 404
}

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/wallets/receipts 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.success) {
            console.log(`Transaction Count: ${result.count}`);
            console.log('\nRecent Transactions:');

            result.transactions.forEach((tx, index) => {
                console.log(`\n${index + 1}. ${tx.raw}`);
            });
        } 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:\Client_Data\Wallets\Default"

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

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

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

# Pretty print JSON output
curl -X GET "http://localhost:8080/api/wallets/transactions?wallet_path=E:\Client_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/wallets/receipts

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

/api/wallets/balance

Get the current balance of a wallet, or the Default wallet if wallet_path is omitted.

/api/wallets/show-coins

View detailed information about coins in specific wallet folders.