events_by_creation_number

Overview

Retrieve events from a specific event stream identified by its creation number. Each event handle has a unique creation number that identifies the event stream at a particular account. This is the legacy event querying mechanism, useful for working with older contracts and event handles.

Endpoint

GET /v1/accounts/{address}/events/{creation_number}

Request

Path Parameters

Name	Type	Required	Description
address	string	Yes	Account address that owns the event stream
creation_number	string	Yes	Event stream creation number (integer as string)

Query Parameters

Name	Type	Required	Description
start	string	No	Starting sequence number for pagination
limit	integer	No	Maximum number of events to return (default: 25, max: 1000)

Response

Success Response (200)

Returns an array of event objects:

[
  {
    "version": "123456789",
    "guid": {
      "creation_number": "0",
      "account_address": "0x1"
    },
    "sequence_number": "42",
    "type": "0x1::coin::WithdrawEvent",
    "data": {
      "amount": "1000000"
    }
  }
]

Each event includes:

• version: Ledger version when the event was emitted
• guid: Globally unique identifier for the event stream
• sequence_number: Sequential number within this event stream
• type: Full Move type of the event payload
• data: The structured event payload

Error Responses

Status	Error Code	Description
400	invalid_input	Invalid address or creation number format
404	resource_not_found	Event stream 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/0?limit=10 \
  -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_creation_number("0x1", "0", start=None, limit=10)
for event in events:
    print(f"Event at version {event['version']}: {event['type']}")

TypeScript example:

const response = await fetch(
  "https://api-aptos-mainnet.n.dwellir.com/YOUR_API_KEY/v1/accounts/0x1/events/0?limit=10",
  { headers: { "Accept": "application/json" } }
);
const events = await response.json();

Use Cases

This endpoint serves several important purposes for event-driven applications:

1. Legacy Contract Integration: Query events from older contracts that use the legacy event handle system (pre-0x1::event::EventHandle model) without requiring contract upgrades.

2. Event Stream Monitoring: Monitor specific event streams for particular activities, such as tracking all coin withdrawal events from the treasury account.

3. Historical Event Analysis: Paginate through historical events to analyze patterns, aggregate statistics, or reconstruct state changes over time.

4. Audit Trail Construction: Build comprehensive audit logs by retrieving all events emitted by critical system accounts in chronological order.

5. Notification Systems: Implement real-time notification systems that poll for new events from specific handles and trigger webhooks or alerts.

6. State Reconstruction: Recreate account or module state by replaying events in sequence, useful for debugging or validation purposes.

Best Practices

Creation Number Discovery: Creation numbers are not easily discoverable without inspecting account resources first. Use the accounts/{address}/resources endpoint to find event handles with their creation numbers.

Pagination Strategy: Start with limit=1000 to minimize API calls for bulk historical retrieval. Use the last event's sequence_number + 1 as the next start parameter for pagination.

Sequence Numbers: Event sequence numbers within a stream are guaranteed to be sequential with no gaps. Missing sequence numbers indicate data synchronization issues.

Version Ordering: While sequence numbers order events within a stream, use the version field to establish ordering across different event streams or accounts.

Legacy vs Modern: For new contracts, prefer the modern event system using 0x1::event::emit(). This endpoint primarily supports legacy code and backwards compatibility.

Rate Limiting: Avoid polling this endpoint too frequently. For real-time needs, consider polling every 5-10 seconds or use the GraphQL indexer with subscriptions when available.

Performance Considerations

Event queries are efficient for reasonable ranges. Fetching 100 events typically completes in 50-100ms. However, requesting the maximum 1000 events can take 200-500ms depending on event payload sizes.

Events are stored in chronological order, making forward pagination (increasing sequence numbers) faster than reverse traversal. The creation number index provides O(1) lookup to the event stream, but scanning requires sequential I/O.

For applications requiring comprehensive event analysis across multiple accounts or event types, the GraphQL indexer provides more efficient bulk querying capabilities with complex filtering and aggregation support.