How to Get On-Chain Time: Sui Clock Object vs Aptos Timestamp

07 November 2026

Both Sui and Aptos provide on-chain time access, but they do so through fundamentally different mechanisms. Sui offers a Clock object that increments on each epoch boundary, while Aptos exposes a timestamp function that returns the block time of the current transaction. The key difference is that Sui's Clock is a shared object that can be passed into transactions, whereas Aptos's timestamp is a global function available in any Move module. This page explains how each system works and how to use them in your Move code.

Sui Clock Object

Sui's approach to on-chain time is deliberate: it doesn't expose the wall clock directly inside transactions. Instead, a system-controlled Clock object is created at the start of each epoch. This object stores a monotonically increasing timestamp, updated at the beginning of the epoch when validators reach consensus on the current time.

How to Use the Sui Clock

1. Import the Clock module in your Move code. The module is sui::clock.
2. Pass the Clock as an argument to your entry function. The Clock is a shared object with ID 0x6 on mainnet and testnet. You must include it explicitly in the transaction's object list.
3. Read the timestamp using clock::timestamp_ms(&clock). This returns a u64 representing milliseconds since Unix epoch.

Example function signature:

public entry fun check_time(clock: &Clock, ctx: &mut TxContext) {
 let now_ms = clock::timestamp_ms(clock);
 // use now_ms
}

The timestamp only updates at epoch boundaries - approximately every 24 hours on Sui mainnet. Within an epoch, the Clock value remains constant. This means Sui's on-chain time is suitable for coarse-grained time checks like expiration windows measured in days, but not for precise timing within a single epoch.

Important notes on sui clock

• The Clock is a shared object, so any transaction reading it will incur a shared object access cost. This is typically negligible.
• You cannot get millisecond precision within an epoch; the value is frozen until the next epoch.
• The timestamp is guaranteed to be non-decreasing across epochs, but not strictly increasing.

Aptos Timestamp

Aptos provides a simpler, more direct mechanism: the aptos_framework::timestamp module exposes a now_microseconds() function that returns the block time of the current transaction. This value is set by validators when they produce a block and is available to any Move function without special imports.

How to Use the Aptos Timestamp

1. Import the timestamp module in your Move code: use aptos_framework::timestamp;
2. Call timestamp::now_microseconds() directly in any function. No special arguments required.
3. The return value is a u64 representing microseconds since Unix epoch.

Example:

public fun check_time(): u64 {
 timestamp::now_microseconds()
}

The Aptos timestamp updates with every block. Since Aptos blocks are produced every 1-2 seconds, the time resolution is much finer than Sui's. This makes Aptos suitable for use cases like high-frequency trading, auction deadlines, or rate limiting that requires second-level precision.

Important notes on aptos timestamp

• The timestamp is valid only during transaction execution. You cannot store it in global storage and later rely on it as an authoritative time source - it becomes stale immediately.
• It is not monotonic across blocks; a block's timestamp can be slightly earlier than the previous block due to clock drift, but validators enforce that it must be within a reasonable window.
• The function is available in all Move modules without permission checks, because the timestamp is part of the block metadata.

Choosing between the two

Use Sui's Clock when you need a persistent, verifiable time that can be stored - for example, to prove that an NFT was minted before a certain epoch. Use Aptos's timestamp when you need real-time granularity within a single block, such as for auction bid deadlines.

Practical Considerations

• No timestamp in Sui entry functions without Clock: If you forget to pass the Clock, you cannot get any on-chain time. This is a common source of errors for developers migrating from Aptos.
• Aptos timestamp is not suitable for long-term proofs: Because the timestamp is not persisted in a verifiable object, you cannot later prove that a specific timestamp was seen. For that, you would need to record the block height or use a custom oracle.
• Both systems are deterministic: During simulation or replay, the timestamp will match the original block's time, not the current wall clock. This is important for testing.

For most applications, the choice depends on whether you need fine-grained timing (Aptos) or a stable, verifiable anchor (Sui). Neither provides true randomness or future time - only the past, as agreed by validators.

Back to sui & aptos