Timestamp

Syntax

Timestamp

The keyword takes no parameters. A history index in square brackets reads earlier bars, so Timestamp[1] gives the closing timestamp of the previous bar.

How it works

A Unix timestamp represents time as the total number of seconds elapsed since the Unix Epoch, 1 January 1970 at 00:00:00 UTC. Timestamp reports that count for the close of each candlestick. The scale is universal: it does not depend on the platform time zone setting, geographical location, or daylight saving rules, which makes it the reliable basis for time arithmetic in trading scripts.

Because the count is linear, subtracting two Timestamp values yields an exact difference in seconds. This is the property that HHMMSS values such as TIME lack, since their digits encode hours and minutes positionally. Typical patterns include storing the timestamp of a reference event in a variable, then comparing later bars against it to measure how much time has passed.

The related keyword OpenTimestamp reports the Unix time of the bar open instead of the close. On a completed bar, Timestamp - OpenTimestamp equals the bar duration. On the live forming bar, Timestamp keeps advancing, so the same expression measures the age of the bar so far.

Examples

Example 1, Seconds elapsed since the week opened (Indicator)

// Store the timestamp of the first bar of each new week
IF DayOfWeek < DayOfWeek[1] THEN
  firstBarTime = Timestamp
ENDIF
RETURN Timestamp - firstBarTime AS "elapsed seconds"

A drop in the day-of-week number marks the first bar of a new week. Its Timestamp is stored, and every following bar plots the number of seconds elapsed since that reference.

Example 2, Exiting a position after a fixed holding time (ProOrder)

// Record the entry time, then exit after two hours on market
IF NOT OnMarket AND close CROSSES OVER Average[50](close) THEN
  BUY 1 CONTRACT AT MARKET
  entryStamp = Timestamp
ENDIF
IF LongOnMarket AND Timestamp - entryStamp >= 7200 THEN
  SELL AT MARKET
ENDIF

The entry bar's Timestamp is saved when the position opens. Once the difference reaches 7200 seconds, two hours, the position is closed regardless of price.

Example 3, Excluding instruments with sparse data (ProScreener)

// Match instruments whose last two bars closed less than a day apart
active = Timestamp - Timestamp[1] < 86400
SCREENER[active] ("Bar age")

Comparing the closing timestamps of the last two bars filters out instruments whose data arrives less often than once per day.

Common errors and gotchas

• Seconds, not milliseconds. ProBuilder timestamps count seconds. Thresholds copied from environments that use millisecond epochs are off by a factor of 1000.
• Close time, not wall clock. On historical bars, Timestamp is the moment that bar closed, not the present time. Treating it as "now" during a backtest replay leads to conditions that were never true historically.
• Not comparable to dates or HHMMSS values. A timestamp such as 1719849600 shares no scale with 20240701 or 140000. Comparisons across formats compile but produce meaningless results.
• Uninitialized reference variables. Patterns such as Timestamp - firstBarTime return the full epoch count until the reference variable is first assigned, since unset variables start at 0. Guard the expression or wait until the reference event has occurred.

Related instructions

• OpenTimestamp, Unix timestamp of the bar open.
• CurrentTime, wall-clock time in HHMMSS format.
• OpenTime, opening time of the bar as an HHMMSS integer.
• TIME, closing time of a bar in HHMMSS format.
• DayOfWeek, day of the week of the bar, useful for weekly anchors.
• Today, date of the current bar in YYYYMMDD format.
• BarIndex, number of bars since the beginning of the loaded history.