Get Events

Query events emitted by Move modules on the Aptos blockchain.

Available Endpoints

• GET /accounts/{address}/events/{creation_number} - Get events by creation number
• GET /accounts/{address}/events/{event_handle}/{field_name} - Get events by event handle

When to Use These Methods

Event queries are essential for:

• DApp Monitoring - Track smart contract activity
• User Notifications - Alert users of on-chain events
• Analytics - Analyze protocol usage patterns
• State Synchronization - Keep off-chain state in sync

Implementation Examples

TypeScript

// Get events by creation number
async function getEventsByCreationNumber(
  address: string,
  creationNumber: number,
  start?: number,
  limit: number = 25
) {
  const url = new URL(
    `https://api-aptos-mainnet.n.dwellir.com/v1/YOUR_API_KEY/accounts/${address}/events/${creationNumber}`
  );
  
  if (start !== undefined) url.searchParams.append('start', start.toString());
  url.searchParams.append('limit', limit.toString());
  
  const response = await fetch(url.toString(), {
    headers: { 'Accept': 'application/json' }
  });
  
  if (!response.ok) {
    throw new Error(`Failed to get events: ${response.statusText}`);
  }
  
  return response.json();
}

// Monitor specific event stream
async function monitorEvents(
  address: string,
  creationNumber: number,
  onEvent: (event: any) => void
) {
  let lastSequence = "0";
  
  setInterval(async () => {
    try {
      const events = await getEventsByCreationNumber(
        address,
        creationNumber,
        parseInt(lastSequence)
      );
      
      for (const event of events) {
        if (BigInt(event.sequence_number) > BigInt(lastSequence)) {
          onEvent(event);
          lastSequence = event.sequence_number;
        }
      }
    } catch (error) {
      console.error("Event monitoring error:", error);
    }
  }, 2000); // Poll every 2 seconds
}

// Parse common event types
function parseTransferEvent(event: any) {
  if (event.type.includes("CoinTransferEvent")) {
    return {
      from: event.data.from,
      to: event.data.to,
      amount: event.data.amount,
      timestamp: event.timestamp,
    };
  }
  return null;
}

Python

import requests
from typing import List, Dict, Optional

def get_events_by_creation_number(
    address: str,
    creation_number: int,
    start: Optional[int] = None,
    limit: int = 25
) -> List[Dict]:
    """Get events by creation number"""
    
    url = f"https://api-aptos-mainnet.n.dwellir.com/v1/YOUR_API_KEY/accounts/{address}/events/{creation_number}"
    
    params = {"limit": limit}
    if start is not None:
        params["start"] = start
    
    response = requests.get(url, params=params, headers={"Accept": "application/json"})
    response.raise_for_status()
    
    return response.json()

def monitor_event_stream(
    address: str,
    creation_number: int,
    callback,
    poll_interval: int = 2
):
    """Monitor a specific event stream"""
    import time
    
    last_sequence = 0
    
    while True:
        try:
            events = get_events_by_creation_number(
                address, 
                creation_number,
                start=last_sequence
            )
            
            for event in events:
                if int(event["sequence_number"]) > last_sequence:
                    callback(event)
                    last_sequence = int(event["sequence_number"])
        
        except Exception as e:
            print(f"Error monitoring events: {e}")
        
        time.sleep(poll_interval)

def parse_coin_events(events: List[Dict]) -> List[Dict]:
    """Parse coin transfer events"""
    
    transfers = []
    
    for event in events:
        if "CoinTransferEvent" in event.get("type", ""):
            transfers.append({
                "from": event["data"].get("from"),
                "to": event["data"].get("to"),
                "amount": event["data"].get("amount"),
                "sequence": event.get("sequence_number"),
                "timestamp": event.get("timestamp")
            })
    
    return transfers

Common Use Cases

1. Transfer Event Tracking

async function trackTransfers(
  coinType: string,
  address: string
): Promise<any[]> {
  // Get account resources to find event handles
  const resources = await aptos.getAccountResources({ 
    accountAddress: address 
  });
  
  const coinStore = resources.find(
    r => r.type === `0x1::coin::CoinStore<${coinType}>`
  );
  
  if (!coinStore) {
    return [];
  }
  
  // Get deposit events
  const depositEvents = await getEventsByCreationNumber(
    address,
    coinStore.data.deposit_events.guid.id.creation_num
  );
  
  // Get withdraw events
  const withdrawEvents = await getEventsByCreationNumber(
    address,
    coinStore.data.withdraw_events.guid.id.creation_num
  );
  
  return {
    deposits: depositEvents,
    withdrawals: withdrawEvents,
  };
}

2. DeFi Protocol Events

async function monitorDeFiEvents(protocolAddress: string) {
  // Common DeFi events to monitor
  const eventTypes = [
    { name: "swap", creationNumber: 1 },
    { name: "liquidity_added", creationNumber: 2 },
    { name: "liquidity_removed", creationNumber: 3 },
    { name: "rewards_claimed", creationNumber: 4 },
  ];
  
  for (const eventType of eventTypes) {
    monitorEvents(
      protocolAddress,
      eventType.creationNumber,
      (event) => {
        console.log(`${eventType.name} event:`, event);
        // Process event based on type
      }
    );
  }
}

3. NFT Activity

async function trackNFTEvents(
  collectionAddress: string,
  tokenId: string
) {
  const events = [];
  
  // Monitor mint events
  const mintEvents = await getEventsByCreationNumber(
    collectionAddress,
    0 // Mint event creation number
  );
  
  // Monitor transfer events
  const transferEvents = await getEventsByCreationNumber(
    collectionAddress,
    1 // Transfer event creation number
  );
  
  // Filter for specific token
  return {
    mints: mintEvents.filter(e => e.data.token_id === tokenId),
    transfers: transferEvents.filter(e => e.data.token_id === tokenId),
  };
}

Need help? Contact our support team or check the Aptos documentation.