Skip to content

Transactions

The transactions resource provides access to payment transaction history on the Grapevine platform.

Overview

Every payment for content creates a transaction record. You can:

  • List transactions with filtering (by payer, recipient, entry)
  • Look up specific transactions by ID or blockchain hash
  • Paginate through large result sets

Methods

MethodDescriptionAuth Required
list()List transactions with filtersNo
get()Get transaction by IDNo
getByHash()Get transaction by blockchain hashNo
paginate()Async generator for paginationNo

Quick Examples

import { GrapevineClient } from '@pinata/grapevine-sdk';
 
const grapevine = new GrapevineClient({ network: 'testnet' });
 
// List recent transactions
const result = await grapevine.transactions.list({ page_size: 10 });
console.log(`Found ${result.data.length} transactions`);
 
// Filter by payer
const myPayments = await grapevine.transactions.list({
  payer: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
});
 
// Filter by recipient (content creator)
const myRevenue = await grapevine.transactions.list({
  pay_to: '0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb'
});
 
// Get specific transaction
const tx = await grapevine.transactions.get('tx-uuid-here');
 
// Look up by blockchain hash
const txByHash = await grapevine.transactions.getByHash('0xabc123...');
 
// Paginate through all transactions
for await (const batch of grapevine.transactions.paginate()) {
  console.log(`Processing ${batch.length} transactions`);
}

Types

Transaction

interface Transaction {
  id: string;                    // UUID
  piid?: string | null;          // Payment Intent ID
  payer: string;                 // Payer wallet address
  pay_to: string;                // Recipient wallet address
  amount: string;                // Amount in wei
  asset: string;                 // Asset type (e.g., "USDC")
  entry_id?: string | null;      // Associated entry ID
  transaction_hash: string;      // Blockchain transaction hash
  created_at: number;            // Unix timestamp
}

ListTransactionsQuery

interface ListTransactionsQuery {
  page_size?: number;    // Results per page (default: 20, max: 100)
  page_token?: string;   // Pagination token
  payer?: string;        // Filter by payer address
  pay_to?: string;       // Filter by recipient address
  entry_id?: string;     // Filter by entry ID
}

Use Cases

Payment History Dashboard

async function getPaymentHistory(walletAddress: string) {
  // Payments made
  const spent = await grapevine.transactions.list({
    payer: walletAddress,
    page_size: 50
  });
  
  // Payments received
  const received = await grapevine.transactions.list({
    pay_to: walletAddress,
    page_size: 50
  });
  
  return {
    spent: spent.data,
    totalSpent: spent.data.reduce(
      (sum, tx) => sum + BigInt(tx.amount), 
      BigInt(0)
    ),
    received: received.data,
    totalReceived: received.data.reduce(
      (sum, tx) => sum + BigInt(tx.amount), 
      BigInt(0)
    )
  };
}

Entry Revenue Analytics

async function getEntryRevenue(entryId: string) {
  const transactions: Transaction[] = [];
  
  for await (const batch of grapevine.transactions.paginate({ entry_id: entryId })) {
    transactions.push(...batch);
  }
  
  const totalRevenue = transactions.reduce(
    (sum, tx) => sum + BigInt(tx.amount),
    BigInt(0)
  );
  
  const uniqueBuyers = new Set(transactions.map(tx => tx.payer)).size;
  
  return {
    transactions,
    totalRevenue: formatUSDC(totalRevenue.toString()),
    purchaseCount: transactions.length,
    uniqueBuyers
  };
}
 
function formatUSDC(weiAmount: string): string {
  const usdc = Number(BigInt(weiAmount)) / 1e6;
  return `${usdc.toFixed(2)}`;
}

Verify Payment

async function verifyPayment(transactionHash: string) {
  try {
    const tx = await grapevine.transactions.getByHash(transactionHash);
    
    return {
      verified: true,
      transaction: tx,
      payer: tx.payer,
      recipient: tx.pay_to,
      amount: formatUSDC(tx.amount),
      entry: tx.entry_id
    };
  } catch (error) {
    if (error.message.includes('404')) {
      return { verified: false, error: 'Transaction not found' };
    }
    throw error;
  }
}

Export Transactions to CSV

async function exportTransactionsToCSV(walletAddress: string) {
  const allTransactions: Transaction[] = [];
  
  // Get all transactions where user is payer or recipient
  for await (const batch of grapevine.transactions.paginate({ payer: walletAddress })) {
    allTransactions.push(...batch);
  }
  
  for await (const batch of grapevine.transactions.paginate({ pay_to: walletAddress })) {
    allTransactions.push(...batch);
  }
  
  // Convert to CSV
  const headers = ['ID', 'Date', 'Type', 'Amount', 'Asset', 'Entry ID', 'Hash'];
  const rows = allTransactions.map(tx => [
    tx.id,
    new Date(tx.created_at * 1000).toISOString(),
    tx.payer === walletAddress ? 'Sent' : 'Received',
    formatUSDC(tx.amount),
    tx.asset,
    tx.entry_id || '',
    tx.transaction_hash
  ]);
  
  return [headers, ...rows].map(row => row.join(',')).join('\n');
}

Related