Skip to main content
GET
/
api
/
v1
/
ledger
/
transactions
/
{user_id}
Get Transaction History
curl --request GET \
  --url https://api.example.com/api/v1/ledger/transactions/{user_id}
{
  "transactions": [
    "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "deadbeefcafebabe1234567890abcdef1234567890abcdef1234567890abcdef"
  ]
}

​
Overview

Retrieves the transaction history for a user within a specified time range. This endpoint returns hex-encoded transaction data that includes payment details, vendor information, and timestamps.
The user_id parameter is a hex-encoded SHA256 hash of the concatenated user-token share and “ledger” string.

​
Path Parameters

​
user_id
string
required
User identifier calculated by concatenating the user-token share with “ledger” string, then hashed using SHA256. Result is a 64-character hex string.

​
Query Parameters

​
from
integer
required
Starting timestamp (Unix timestamp in seconds)
​
to
integer
Ending timestamp (Unix timestamp in seconds). If omitted, returns all transactions from ‘from’ to now

​
Response

​
transactions
array
required
Array of hex-encoded transaction data strings. Each string contains a JSON-encoded Transaction object with payment details, vendor info, and attributes.
{
  "transactions": [
    "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
    "deadbeefcafebabe1234567890abcdef1234567890abcdef1234567890abcdef"
  ]
}

​
Usage Examples

async function getUserTransactionHistory(userTokenShare, fromTimestamp, toTimestamp = null) {
  const crypto = require('crypto');

  // Calculate user_id for ledger
  const userId = crypto
    .createHash('sha256')
    .update(userTokenShare + 'ledger')
    .digest('hex');

  let url = `https://dev.app.boop.it/api/v1/ledger/transactions/${userId}?from=${fromTimestamp}`;
  if (toTimestamp) {
    url += `&to=${toTimestamp}`;
  }

  const response = await fetch(url, {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  });

  const { transactions } = await response.json();

  // Decode hex-encoded transaction data
  return transactions.map(hexString => {
    const jsonString = Buffer.from(hexString, 'hex').toString('utf8');
    return JSON.parse(jsonString);
  });
}

// Usage
const lastMonth = Math.floor(Date.now() / 1000) - (30 * 24 * 60 * 60);
const history = await getUserTransactionHistory(userTokenShare, lastMonth);

​
Transaction Data Structure

Each hex-encoded transaction string contains a JSON object with: 
{
  "user-id": "a1b2c3d4e5f6789012345678901234567890abcdef1234567890abcdef123456",
  "context-id": "550e8400-e29b-41d4-a716-446655440000",
  "attributes": [
    {
      "type": "pseudonym",
      "context": null
    }
  ],
  "vendor": {
    "id": "vendor123",
    "url": "https://vendor.example.com"
  },
  "timestamp": 1609459200000,
  "result": {
    "code": "ok"
  }
}

​
Common Use Cases

​
User Dashboard

Display transaction history in user wallets: 
async function displayUserTransactions(userTokenShare) {
  const last30Days = Math.floor(Date.now() / 1000) - (30 * 24 * 60 * 60);
  const transactions = await getUserTransactionHistory(userTokenShare, last30Days);

  return transactions.map(tx => ({
    vendor: tx.vendor.id,
    amount: tx.attributes.find(a => a.type === 'payment')?.context || 0,
    timestamp: new Date(tx.timestamp),
    success: tx.result.code === 'ok'
  }));
}

​
Analytics and Reporting

Generate spending reports for vendors: 
async function generateVendorReport(userTokenShare, startDate, endDate) {
  const start = Math.floor(startDate.getTime() / 1000);
  const end = Math.floor(endDate.getTime() / 1000);

  const transactions = await getUserTransactionHistory(userTokenShare, start, end);

  const report = transactions.reduce((acc, tx) => {
    if (tx.result.code === 'ok') {
      acc.totalSpent += tx.amount || 0;
      acc.successfulTransactions++;
    } else {
      acc.failedTransactions++;
    }
    return acc;
  }, { totalSpent: 0, successfulTransactions: 0, failedTransactions: 0 });

  return report;
}

​
Time Range Guidelines

  • Maximum range: 90 days per request
  • Timestamps: Unix timestamps in seconds
  • Timezone: All timestamps are in UTC

​
Security Considerations

  • Never expose user-token shares in client-side code
  • Calculate user_id server-side only
  • Implement proper pagination for large date ranges
  • Use HTTPS for all transaction history requests
  • Consider caching for frequently accessed data

​
Rate Limits

  • 50 history requests per minute per API key
  • 500 history requests per hour per API key