events_by_handle

Endpoint

GET /v1/accounts/{address}/events/{event_handle}/{field_name}

Request

Path Parameters

Name	Type	Required	Description
address	string	Yes	Account address
event_handle	string	Yes	Struct type with events
field_name	string	Yes	Field in the struct producing events

Query Parameters

Name	Type	Required	Description
start	string	No	Starting sequence
limit	integer	No	Page size

Response

Success Response (200)

Returns an array of event objects from the specified handle:

[
  {
    "version": "123456789",
    "guid": {
      "creation_number": "3",
      "account_address": "0x1"
    },
    "sequence_number": "5",
    "type": "0x1::account::CoinRegisterEvent",
    "data": {
      "type_info": {
        "account_address": "0x1",
        "module_name": "aptos_coin",
        "struct_name": "AptosCoin"
      }
    }
  }
]

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid address, handle, or field name format
404	resource_not_found	Event handle or field doesn't exist
404	account_not_found	Account doesn't exist

Code Examples

curl -X GET "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/accounts/0x1/events/0x1::account::Account/coin_register_events?limit=5" \
  -H "Accept: application/json"

Python example:

from aptos_sdk.client import RestClient

client = RestClient("https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1")
events = client.account_events_by_event_handle(
    "0x1",
    "0x1::account::Account",
    "coin_register_events",
    limit=5
)

TypeScript example:

const events = await aptos.getEventsByEventHandle({
  accountAddress: "0x1",
  eventHandleStruct: "0x1::account::Account",
  fieldName: "coin_register_events",
  minimumLedgerVersion: 0,
  options: { limit: 5 }
});

Use Cases

This endpoint enables powerful event-driven architecture patterns:

1. Contract Event Monitoring: Monitor specific event types emitted by smart contracts, such as tracking all token transfer events or NFT mint events from a marketplace contract.

2. User Activity Tracking: Build user activity feeds by querying events from user-controlled resources, showing transaction history and state changes.

3. Cross-Contract Analytics: Aggregate events across multiple contracts or accounts to analyze ecosystem-wide trends, such as total trading volume or user adoption metrics.

4. Real-Time Notifications: Poll event handles to detect new events and trigger notifications, webhooks, or automated responses for critical contract activities.

5. State Verification: Verify that expected state changes occurred by checking for corresponding events, useful for transaction confirmation UIs.

6. Debugging and Testing: During development, inspect event emissions to validate contract behavior and ensure events are emitted with correct data.

Best Practices

Event Handle Structure: The event handle path follows the pattern address::module::Struct/field_name. The struct must contain an EventHandle<T> field with the specified name.

Type Information: Always inspect the returned type field to understand the event payload structure. Event types are strongly typed in Move and the type string indicates the exact Move struct emitted.

Pagination: For event streams with many events, use pagination with the start parameter set to the last seen sequence_number + 1 to avoid missing events or duplicates.

Polling Frequency: Poll at reasonable intervals (5-30 seconds) based on your use case. Too frequent polling wastes resources, while too infrequent polling may delay notifications.

Handle Discovery: Find available event handles by querying account resources and inspecting struct fields of type EventHandle<T>. The ABI from module queries shows event handle field names.

Performance Considerations

Event queries by handle are optimized with indexed lookups, typically completing in 50-150ms for reasonable limits. Response times increase with larger limit values and complex event payload structures.

This method is more efficient than querying by creation number when you know the specific contract and field name, as it avoids resource enumeration overhead. However, for bulk event analysis across many handles, consider using the GraphQL indexer for better query flexibility and performance.