Get Transactions

Retrieve transaction history for a customer's wallet with pagination and filtering by network, currency, or status.

Endpoint

GET /api/v1/wallet/customer/:customerID/transactions

Authentication

Requires API key authentication via X-API-Key header.

Path Parameters

Parameter	Type	Description
`customerID`	string	Customer identifier

Query Parameters

Parameter	Type	Required	Description
`page`	integer	No	Page number (default: 1)
`limit`	integer	No	Results per page (default: 20, max: 100)
`network`	string	No	Filter by network (BTC, ETH, BSC, etc.)
`currency`	string	No	Filter by currency (BTC, ETH, USDT, etc.)
`status`	string	No	Filter by status (pending, confirmed, failed)

Example Request

JavaScriptPythoncURL

javascript

// Get all transactions
const response = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transactions?page=1&limit=20',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

const data = await response.json();
console.log(`Total transactions: ${data.total}`);
console.log('Transactions:', data.transactions);

// Filter by network and status
const filtered = await fetch(
  'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transactions?network=ETH&status=confirmed',
  {
    headers: {
      'X-API-Key': 'your-api-key'
    }
  }
);

python

import requests

# Get all transactions
response = requests.get(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transactions',
    headers={'X-API-Key': 'your-api-key'},
    params={'page': 1, 'limit': 50}
)

data = response.json()
for txn in data['transactions']:
    print(f"{txn['network']} - {txn['txn_hash']} - {txn['status']}")

# Filter by currency
usdt_txns = requests.get(
    'https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transactions',
    headers={'X-API-Key': 'your-api-key'},
    params={'currency': 'USDT'}
).json()

bash

# Get all transactions
curl "https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transactions?page=1&limit=20" \
  -H "X-API-Key: your-api-key"

# Filter by network
curl "https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/user_12345/transactions?network=BTC" \
  -H "X-API-Key: your-api-key"

Response

Success Response (200 OK)

Field	Type	Description
`customer_id`	string	Customer identifier
`transactions`	array	Array of transaction objects
`page`	integer	Current page number
`limit`	integer	Results per page
`total`	integer	Total number of transactions

Transaction Object

Field	Type	Description
`id`	integer	Transaction database ID
`txn_hash`	string	Blockchain transaction hash
`network`	string	Blockchain network
`currency`	string	Currency
`type`	string	Transaction type (send, receive)
`from_address`	string	Sender address
`to_address`	string	Recipient address
`amount`	string	Amount in smallest unit
`gas_fee`	string	Transaction fee
`status`	string	Transaction status
`confirmations`	integer	Number of confirmations
`timestamp`	string	Transaction timestamp

json

{
  "customer_id": "user_12345",
  "transactions": [
    {
      "id": 501,
      "txn_hash": "0x1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6p7q8r9s0t1u2v3w4x5y6z7a8b9c0d1e2f",
      "network": "ETH",
      "currency": "ETH",
      "type": "send",
      "from_address": "0x8B3192f2f0f0D7E4F5C3A1B9E2D7A6C5B4D3E2F1",
      "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "amount": "100000000000000000",
      "gas_fee": "630000000000000",
      "status": "confirmed",
      "confirmations": 12,
      "timestamp": "2026-01-03T03:00:00Z"
    },
    {
      "id": 502,
      "txn_hash": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh_incoming",
      "network": "BTC",
      "currency": "BTC",
      "type": "receive",
      "from_address": "bc1q8c6fshw2dlwun7ekn9qwf37cu2rn755u9yrf",
      "to_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
      "amount": "5000000",
      "gas_fee": "0",
      "status": "confirmed",
      "confirmations": 6,
      "timestamp": "2026-01-03T02:30:00Z"
    },
    {
      "id": 503,
      "txn_hash": "0xabc123def456...",
      "network": "BSC",
      "currency": "USDT",
      "type": "send",
      "from_address": "0x8B3192f2f0f0D7E4F5C3A1B9E2D7A6C5B4D3E2F1",
      "to_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "amount": "50000000",
      "gas_fee": "200000000000000",
      "status": "pending",
      "confirmations": 0,
      "timestamp": "2026-01-03T04:10:00Z"
    }
  ],
  "page": 1,
  "limit": 20,
  "total": 157
}

Error Responses

404 Not Found

json

{
  "error": "Wallet not found"
}

500 Internal Server Error

json

{
  "error": "Failed to fetch transactions"
}

Transaction Types

Type	Description	From Your Perspective
`send`	Outgoing transaction	You sent funds
`receive`	Incoming transaction	You received funds

Transaction Status

Status	Description	Confirmations	Next Action
`pending`	Broadcast to network	0	Wait for confirmation
`confirmed`	Included in block	1+	Complete
`failed`	Transaction failed	N/A	Retry if needed

Use Cases

Transaction History UI

Display paginated transaction history:

javascript

async function loadTransactionHistory(customerId, page = 1) {
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/transactions?page=${page}&limit=20`,
    {
      headers: { 'X-API-Key': process.env.API_KEY }
    }
  );
  
  const data = await response.json();
  
  return {
    transactions: data.transactions.map(txn => ({
      ...txn,
      amount_formatted: formatAmount(txn.amount, txn.currency),
      timestamp_formatted: new Date(txn.timestamp).toLocaleString(),
      explorer_url: getExplorerUrl(txn.network, txn.txn_hash)
    })),
    total: data.total,
    hasMore: page * 20 < data.total
  };
}

function formatAmount(amount, currency) {
  const decimals = getDecimals(currency);
  return (parseFloat(amount) / Math.pow(10, decimals)).toFixed(6);
}

function getExplorerUrl(network, txnHash) {
  const explorers = {
    BTC: `https://www.blockchain.com/btc/tx/${txnHash}`,
    ETH: `https://etherscan.io/tx/${txnHash}`,
    BSC: `https://bscscan.com/tx/${txnHash}`,
    POL: `https://polygonscan.com/tx/${txnHash}`
  };
  return explorers[network] || '#';
}

Filter Controls

Implement transaction filtering:

javascript

async function filterTransactions(customerId, filters) {
  const params = new URLSearchParams({
    page: filters.page || 1,
    limit: filters.limit || 20,
    ...(filters.network && { network: filters.network }),
    ...(filters.currency && { currency: filters.currency }),
    ...(filters.status && { status: filters.status })
  });
  
  const response = await fetch(
    `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/transactions?${params}`,
    {
      headers: { 'X-API-Key': process.env.API_KEY }
    }
  );
  
  return response.json();
}

// Usage
const ethTransactions = await filterTransactions('user_12345', {
  network: 'ETH',
  status: 'confirmed'
});

const pendingTransfers = await filterTransactions('user_12345', {
  status: 'pending'
});

Export to CSV

Export transaction history:

javascript

async function exportTransactionsCSV(customerId) {
  // Fetch all transactions
  let allTransactions = [];
  let page = 1;
  let hasMore = true;
  
  while (hasMore) {
    const response = await fetch(
      `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${customerId}/transactions?page=${page}&limit=100`,
      {
        headers: { 'X-API-Key': process.env.API_KEY }
      }
    );
    
    const data = await response.json();
    allTransactions = allTransactions.concat(data.transactions);
    
    hasMore = page * 100 < data.total;
    page++;
  }
  
  // Convert to CSV
  const csv = [
    ['Date', 'Network', 'Type', 'Currency', 'Amount', 'Fee', 'Status', 'Hash'].join(','),
    ...allTransactions.map(txn => [
      new Date(txn.timestamp).toISOString(),
      txn.network,
      txn.type,
      txn.currency,
      formatAmount(txn.amount, txn.currency),
      formatAmount(txn.gas_fee, txn.network),
      txn.status,
      txn.txn_hash
    ].join(','))
  ].join('\n');
  
  // Download
  const blob = new Blob([csv], { type: 'text/csv' });
  const url = URL.createObjectURL(blob);
  const a = document.createElement('a');
  a.href = url;
  a.download = `transactions_${customerId}_${Date.now()}.csv`;
  a.click();
}

Real-time Updates

Poll for new transactions:

javascript

class TransactionMonitor {
  constructor(customerId, apiKey) {
    this.customerId = customerId;
    this.apiKey = apiKey;
    this.lastCheck = new Date();
    this.interval = null;
  }
  
  async checkForNew() {
    const response = await fetch(
      `https://payments-api-dev-966260606560.europe-west2.run.app/api/v1/wallet/customer/${this.customerId}/transactions?page=1&limit=10`,
      {
        headers: { 'X-API-Key': this.apiKey }
      }
    );
    
    const data = await response.json();
    
    // Find new transactions since last check
    const newTxns = data.transactions.filter(txn => 
      new Date(txn.timestamp) > this.lastCheck
    );
    
    if (newTxns.length > 0) {
      this.onNewTransactions(newTxns);
    }
    
    this.lastCheck = new Date();
  }
  
  start(callback, intervalMs = 30000) {
    this.onNewTransactions = callback;
    this.interval = setInterval(() => this.checkForNew(), intervalMs);
  }
  
  stop() {
    if (this.interval) {
      clearInterval(this.interval);
    }
  }
}

// Usage
const monitor = new TransactionMonitor('user_12345', process.env.API_KEY);
monitor.start((newTxns) => {
  console.log(`${newTxns.length} new transactions!`);
  newTxns.forEach(txn => {
    showNotification(`New ${txn.type}: ${txn.amount} ${txn.currency}`);
  });
}, 30000); // Check every 30 seconds

Best Practices

Transaction History

Pagination: Always use pagination for better performance
Caching: Cache transaction data on your frontend
Real-time updates: Poll every 30-60 seconds for pending transactions
Status tracking: Monitor pending transactions until confirmed
Export: Provide CSV/PDF export for user records
Block explorer links: Link to blockchain explorers for verification

Transfer - Send cryptocurrency
List Addresses - View wallet addresses
Derive Address - Create addresses for deposits

Get Transactions ​

Endpoint ​

Authentication ​

Path Parameters ​

Query Parameters ​

Example Request ​

Response ​

Success Response (200 OK) ​

Transaction Object ​

Error Responses ​

404 Not Found ​

500 Internal Server Error ​

Transaction Types ​

Transaction Status ​

Use Cases ​

Transaction History UI ​

Filter Controls ​

Export to CSV ​

Real-time Updates ​

Best Practices ​

Related Endpoints ​

Get Transactions

Endpoint

Authentication

Path Parameters

Query Parameters

Example Request

Response

Success Response (200 OK)

Transaction Object

Error Responses

404 Not Found

500 Internal Server Error

Transaction Types

Transaction Status

Use Cases

Transaction History UI

Filter Controls

Export to CSV

Real-time Updates

Best Practices

Related Endpoints