List Transactions

List transactions with filtering and pagination support.

GET/v1/transactions

Overview

Retrieve a paginated list of transactions on the platform. Supports filtering by payer, recipient, or specific entry.

Authentication

Required: No
Payment: No

Public endpoint - no authentication needed.

Parameters

Query Parameters

Parameter	Type	Required	Description
`page_size`	number	No	Number of results per page (default: 20, max: 100)
`page_token`	string	No	Pagination token for next page
`payer`	string	No	Filter by payer wallet address (0x prefixed)
`pay_to`	string	No	Filter by recipient wallet address (0x prefixed)
`entry_id`	string (UUID)	No	Filter by specific feed entry

Response

Status: 200 OK

{
  "transactions": [
    {
      "id": "string",
      "payer": "string",
      "pay_to": "string", 
      "amount": "string",
      "asset": "string",
      "entry_id": "string",
      "transaction_hash": "string",
      "created_at": number
    }
  ],
  "pagination": {
    "total_count": number,
    "page_size": number,
    "next_page_token": "string",
    "has_more": boolean
  }
}

Response Fields

Transaction Object

Field	Type	Description
`id`	string	Unique transaction identifier
`payer`	string	Wallet address that made the payment
`pay_to`	string	Wallet address that received the payment
`amount`	string	Payment amount in wei
`asset`	string	Payment asset type (e.g., "USDC")
`entry_id`	string	Associated feed entry ID (nullable)
`transaction_hash`	string	Blockchain transaction hash
`created_at`	number	Transaction timestamp

Pagination Object

Field	Type	Description
`total_count`	number	Total number of matching transactions
`page_size`	number	Number of results in current page
`next_page_token`	string	Token for fetching next page (null if last page)
`has_more`	boolean	Whether more results are available

Usage Examples

cURL

# Get all transactions (latest first)
curl "https://api.grapevine.fyi/v1/transactions"
 
# Get transactions for specific payer
curl "https://api.grapevine.fyi/v1/transactions?payer=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
 
# Get transactions for specific entry
curl "https://api.grapevine.fyi/v1/transactions?entry_id=123e4567-e89b-12d3-a456-426614174000"
 
# Paginated request
curl "https://api.grapevine.fyi/v1/transactions?page_size=50&page_token=eyJ..."

Example Response

{
  "transactions": [
    {
      "id": "tx_456e7890-e89b-12d3-a456-426614174111",
      "payer": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "pay_to": "0x8Ba1f109551bD432803012645Hac136c8cb2bc43",
      "amount": "1200000",
      "asset": "USDC",
      "entry_id": "123e4567-e89b-12d3-a456-426614174000",
      "transaction_hash": "0xabc123def456...",
      "created_at": 1704067200
    },
    {
      "id": "tx_789a0123-e89b-12d3-a456-426614174222", 
      "payer": "0x1A2b3C4d5E6f7G8h9I0j1K2l3M4n5O6p7Q8r9S0t",
      "pay_to": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
      "amount": "500000",
      "asset": "USDC",
      "entry_id": "456f7890-e89b-12d3-a456-426614174111",
      "transaction_hash": "0xdef456abc123...",
      "created_at": 1704066000
    }
  ],
  "pagination": {
    "total_count": 1247,
    "page_size": 20,
    "next_page_token": "eyJjdXJzb3IiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiIsImlkIjoidHhfNzg5YTAxMjMifQ",
    "has_more": true
  }
}

Use Cases

1. Transaction History

Display transaction history for a user's wallet.

2. Entry Analytics

Track payments for specific content entries.

3. Revenue Reports

Generate revenue reports by filtering recipient transactions.

4. Payment Auditing

Audit and verify payment flows on the platform.

5. Marketplace Analytics

Analyze platform-wide transaction patterns.

Filtering Examples

Get Payments Made by Wallet

curl "https://api.grapevine.fyi/v1/transactions?payer=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

Get Payments Received by Wallet

curl "https://api.grapevine.fyi/v1/transactions?pay_to=0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"

Get Payments for Specific Content

curl "https://api.grapevine.fyi/v1/transactions?entry_id=123e4567-e89b-12d3-a456-426614174000"

Combined Filters

curl "https://api.grapevine.fyi/v1/transactions?payer=0x742d35Cc&pay_to=0x8Ba1f1&page_size=10"

Pagination

The API uses cursor-based pagination for efficient traversal:

First Request: Omit page_token
Subsequent Requests: Use next_page_token from previous response
End Condition: has_more is false or next_page_token is null

Pagination Example

async function getAllUserTransactions(walletAddress: string) {
  const transactions = [];
  let pageToken = null;
  
  do {
    const params = new URLSearchParams({
      payer: walletAddress,
      page_size: '100'
    });
    
    if (pageToken) {
      params.set('page_token', pageToken);
    }
    
    const response = await fetch(
      `https://api.grapevine.fyi/v1/transactions?${params}`
    );
    const data = await response.json();
    
    transactions.push(...data.transactions);
    pageToken = data.pagination.next_page_token;
    
  } while (pageToken);
  
  return transactions;
}

Performance Notes

Ordering: Results ordered by transaction ID descending (newest first)
Caching: Responses cached for 60 seconds
Rate Limits: Standard rate limits apply (100 requests/hour)
Page Size: Maximum page size is 100 transactions

Error Responses

400 Bad Request

{
  "error": "Invalid parameter format",
  "code": "INVALID_PARAMETER",
  "details": "payer must be a valid Ethereum address"
}

422 Unprocessable Entity

{
  "error": "Invalid page token",
  "code": "INVALID_PAGE_TOKEN"
}

Related Endpoints

Create Entry Access Link - Generate access links that create transactions
Get Wallet Stats - View wallet transaction summaries
Get Entry - View content that generates transactions

External Playground

Try this endpoint interactively in Swagger UI:
https://api.grapevine.fyi/v1/docs