/api/wallet/transactions

GET

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

Description

The `/api/wallet/transactions` endpoint returns the most recent transaction history from the active wallet. 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
⚠️ Prerequisites

An active wallet must be selected before calling this endpoint. Use /api/wallet/switch to activate a wallet if needed.

Parameters

This endpoint accepts optional query parameters to control the number of transactions returned.

Query Parameters

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

status string
Always "success" for successful requests.
operation string
Always "wallet-transactions".
wallet string
Name of the active wallet.
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
Currency symbol (typically "CC" for CloudCoin).
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": "CC",
      "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": "CC",
      "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';

async function getWalletTransactions(limit = 10) {
    try {
        const url = `${API_HOST}/api/wallet/transactions?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
getWalletTransactions(10);

// Get last 50 transactions
getWalletTransactions(50);

cURL

# Get last 10 transactions (default)
curl -X GET "http://localhost:8080/api/wallet/transactions"

# Get last 25 transactions
curl -X GET "http://localhost:8080/api/wallet/transactions?limit=25"

# Get maximum allowed transactions (100)
curl -X GET "http://localhost:8080/api/wallet/transactions?limit=100"

# Pretty print JSON output
curl -X GET "http://localhost:8080/api/wallet/transactions?limit=10" | json_pp

Go

package main

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

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

type Transaction struct {
    Date        string `json:"date"`
    Time        string `json:"time"`
    Symbol      string `json:"symbol"`
    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"`
}

func GetWalletTransactions(limit int) (*TransactionsResponse, error) {
    url := fmt.Sprintf("%s/api/wallet/transactions?limit=%d", ApiHost, limit)
    resp, err := http.Get(url)
    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 main() {
    result, err := GetWalletTransactions(10)
    if err != nil {
        panic(err)
    }

    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)
    }
}

Implementation Details

📊 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

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.