Events — Move REST API on Movement

Overview

Events on Movement are the primary mechanism for Move modules to emit observable, indexed data about on-chain actions. Every token transfer, swap, liquidity change, and governance vote produces events that off-chain applications can query. This endpoint lets you retrieve events by account address and creation number, with support for pagination and sequence filtering.

Events are append-only and immutable. Once emitted, an event cannot be modified or deleted, making the event log a reliable audit trail for on-chain activity.

Operational note: On Dwellir shared Movement mainnet, this route depends on indexer-backed event readers. If the node returns internal_error because the indexer reader is unavailable, use the owning resource or an indexer-backed fallback as your source of truth.

Endpoint

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

Base URL: https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1

Understanding Event Handles

In Move, events are emitted through event handles stored as fields in account resources. Each event handle has:

• Creation number -- A unique identifier assigned when the event handle is created. This is what you pass in the URL path.
• Sequence number -- An auto-incrementing counter for events emitted through this handle. Starts at 0 and increases by 1 for each event.

For example, the CoinStore resource for a token contains two event handles:

• deposit_events -- Events emitted when tokens are deposited.
• withdraw_events -- Events emitted when tokens are withdrawn.

To find the creation number for a specific event handle, query the account's resources and look at the event handle fields.

Code Examples

Query Deposit Events

# Get the first 10 events from creation number 2 (deposit events)
curl -s "https://api-movement-mainnet.n.dwellir.com/YOUR_API_KEY/v1/accounts/0xYOUR_ADDRESS/events/2?limit=10" \
  -H "Accept: application/json" | jq '.[] | {seq: .sequence_number, type: .type, data: .data}'

Paginated Event Streaming

Find Event Handle Creation Numbers

Common Use Cases

Token Transfer Monitoring

Track all deposits and withdrawals for an account by querying the deposit_events and withdraw_events handles on the CoinStore resource. This is the foundation for wallet transaction histories and accounting integrations.

DeFi Activity Indexing

Index swap events, liquidity additions, and yield harvests from DeFi protocol modules. Each protocol defines custom event types with specific data structures. Use the event type field to filter and parse events from different protocols.

Real-Time Event Polling

Build a polling loop that periodically checks for new events by tracking the last seen sequence number. With Movement's 1-3 second finality, polling every 2-3 seconds provides near real-time event visibility without overwhelming the RPC endpoint.

Movement-Specific Notes

• Event handles are stored in account resources. To find the creation number for a specific event type, first query the account's resources and inspect the event handle fields.
• Events are guaranteed to be ordered by sequence number within a single event handle. Across different handles, use the version field to determine chronological order.
• The type field uses the fully qualified Move type path (e.g., 0x1::coin::DepositEvent). Use this to filter events by type in your application logic.

Related Endpoints

• GET /v1/accounts/{address} -- Get basic account info.
• GET /v1/accounts/{address}/resources -- List resources that contain event handles.
• GET /v1/transactions/by_hash/{hash} -- Get transaction details including emitted events.
• POST /v1/view -- Call view functions to read current state.