# Finance: Message Timestamps

Industry: Finance

Trading and payment messages carry timestamps in their own formats, and FIX is the one most
systems meet first. A FIX `UTCTimestamp` is written `YYYYMMDD-HH:MM:SS`, with an optional fraction
of a second after a period, and it is always UTC. It is not ISO 8601: it has no dashes in the date,
no `T`, and no `Z`.

SWIFT MT messages carry a different kind of date: a six-digit value date, `YYMMDD`. Most
cross-border payment instructions between banks moved from MT to ISO 20022 on 22 November 2025,
but messages such as MT 101 and MT 910 still carry this date, and so do archived messages. A
two-digit year has no century until someone states one. For value dates, SWIFT states it, so the
SWIFT functions below need no window from you.

What makes it worth a layer is that the stamp states how precisely it was measured, and it does so
by its length. Three fraction digits are milliseconds, six microseconds, nine nanoseconds and
twelve picoseconds. A reader that turns the stamp into a plain instant loses that, and one that
widens it invents digits nobody measured. The functions here read and write the stamp and keep
what the digits say.

```typescript
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";
import { formatFixUtcTimestamp } from "@northguild/gmt/finance/format";
import { isValidFixUtcTimestamp } from "@northguild/gmt/finance/validate";
import { parseSwiftDate } from "@northguild/gmt/finance/parse";
import { formatSwiftDate } from "@northguild/gmt/finance/format";
import { isValidSwiftDate } from "@northguild/gmt/finance/validate";
```

The functions live in `@northguild/gmt/finance/parse`, `@northguild/gmt/finance/format` and
`@northguild/gmt/finance/validate`. The leap seconds they read come from
[`timescale/`](/gmt/reference/timescale/), which is Core: [Leap Seconds and
TAI](/gmt/guides/core-date-operations/leap-seconds-and-tai/) explains the table. Which FIX field
carries which stamp (`SendingTime`, `TransactTime`) is the message's business, not this layer's.

## Reading a FIX timestamp

[`parseFixUtcTimestamp(value)`](/gmt/reference/finance/parse/parseFixUtcTimestamp/) reads a stamp and
returns an object with four fields: the `instant` as a standard UTC string, the `precision` the
digits state, whether the second is a `leapSecond`, and the `picoseconds`. It returns `null` for
anything that is not a valid stamp.

```typescript
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

parseFixUtcTimestamp("20240615-14:30:00");
// { instant: "2024-06-15T14:30:00Z", precision: "second", leapSecond: false, picoseconds: 0 }
parseFixUtcTimestamp("20240615-14:30:00.123");
// { instant: "2024-06-15T14:30:00.123Z", precision: "millisecond", leapSecond: false, picoseconds: 0 }
parseFixUtcTimestamp("20240615-14:30:00.123456");
// { instant: "2024-06-15T14:30:00.123456Z", precision: "microsecond", leapSecond: false, picoseconds: 0 }
parseFixUtcTimestamp("20240615-14:30:00.123456789");
// { instant: "2024-06-15T14:30:00.123456789Z", precision: "nanosecond", leapSecond: false, picoseconds: 0 }
parseFixUtcTimestamp("20240615-14:30:00.123456789012");
// { instant: "2024-06-15T14:30:00.123456789Z", precision: "picosecond", leapSecond: false, picoseconds: 12 }
```

The five precisions are `"second"`, `"millisecond"`, `"microsecond"`, `"nanosecond"` and
`"picosecond"`. The shape is strict, as FIX states it: the dash, the colons and the period are
required, and a month the date lacks, an hour of 24 or a minute of 60 is refused.

```typescript
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

parseFixUtcTimestamp("2024-06-15T14:30:00Z");
// null (an ISO 8601 string, not a FIX stamp)
parseFixUtcTimestamp("20240631-10:00:00");
// null (no 31 June)
parseFixUtcTimestamp("20240615-24:00:00");
// null (hour 24)
```

## Precision is in the digits

The fraction is not a decimal of any width. `.100` states milliseconds, so it is a millisecond
stamp that happens to end in zeros, and it is not `.1`, a tenth of a second. The instant keeps the
digits that were sent, trailing zeros included, so the precision survives the trip.

```typescript
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

parseFixUtcTimestamp("20240615-14:30:00.100");
// { instant: "2024-06-15T14:30:00.100Z", precision: "millisecond", leapSecond: false, picoseconds: 0 }
parseFixUtcTimestamp("20240615-14:30:00.000");
// { instant: "2024-06-15T14:30:00.000Z", precision: "millisecond", leapSecond: false, picoseconds: 0 }
```

A standard instant holds nanoseconds, and a picosecond stamp has twelve digits. The instant keeps
the first nine, and the last three come back beside it as `picoseconds`, a number from 0 to 999.
The parser never cuts a value without saying so.

A fraction of any other width, such as `.12` or `.1234`, is a bilateral agreement between two
counterparties. FIX names no precision for it and a value does not carry the agreement, so the
parser returns `null` and does not guess. If both sides of a link have agreed a width, read the
stamp with [`parseDateTimeWithPattern`](/gmt/reference/plain/parse/parseDateTimeWithPattern/) and a
pattern that states it.

```typescript
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

parseFixUtcTimestamp("20240615-14:30:00.12");
// null (two digits is no FIX precision)
parseFixUtcTimestamp("20240615-14:30:00.1234");
// null
```

## Writing at the precision asked for

[`formatFixUtcTimestamp(value, precision)`](/gmt/reference/finance/format/formatFixUtcTimestamp/)
writes an instant as a FIX stamp of the width you ask for. An offset or a zone on the input is
converted to UTC first, because the stamp is UTC. It returns `""` when it cannot write one.

```typescript
import { formatFixUtcTimestamp } from "@northguild/gmt/finance/format";

formatFixUtcTimestamp("2024-06-15T14:30:00.123456789Z", "second");
// "20240615-14:30:00"
formatFixUtcTimestamp("2024-06-15T14:30:00.123456789Z", "millisecond");
// "20240615-14:30:00.123"
formatFixUtcTimestamp("2024-06-15T14:30:00.123456789Z", "nanosecond");
// "20240615-14:30:00.123456789"
formatFixUtcTimestamp("2024-06-15T14:30:00.123456789Z", "picosecond");
// "20240615-14:30:00.123456789000"
formatFixUtcTimestamp("2024-06-15T16:30:00.123+02:00", "millisecond");
// "20240615-14:30:00.123"
formatFixUtcTimestamp("2024-06-15T10:30:00.5-04:00", "microsecond");
// "20240615-14:30:00.500000"
```

Asking for a width wider than the instant holds pads with zeros, and `"picosecond"` ends in
`000`, because a standard instant carries no digits past nanoseconds.

### Cut, never rounded

Narrowing cuts the fraction and does not round it. Rounding can carry into the next second, the
next minute or the next day, and a stamp that moved forward names a moment that had not happened
when the trade was stamped.

```typescript
import { formatFixUtcTimestamp } from "@northguild/gmt/finance/format";

formatFixUtcTimestamp("2024-06-15T23:59:59.9996Z", "millisecond");
// "20240615-23:59:59.999" (rounded, it would be the next day at 00:00:00.000)
formatFixUtcTimestamp("2024-06-15T23:59:59.9996Z", "second");
// "20240615-23:59:59"
formatFixUtcTimestamp("2024-06-15T23:59:59.9996Z", "microsecond");
// "20240615-23:59:59.999600"
```

### A local time is not a UTC stamp

A date-time with no offset names no UTC second, so the formatter refuses it and returns `""`.
Resolve it in its zone first with [`resolveLocal`](/gmt/reference/instant/convert/resolveLocal/), which
makes the choice for a repeated or skipped wall time explicit, and then write the instant.

```typescript
import { formatFixUtcTimestamp } from "@northguild/gmt/finance/format";
import { resolveLocal } from "@northguild/gmt/instant/convert";

formatFixUtcTimestamp("2024-06-15T14:30:00", "millisecond");
// ""
resolveLocal("2024-06-15T14:30:00", "America/New_York");
// "2024-06-15T18:30:00Z"
formatFixUtcTimestamp(resolveLocal("2024-06-15T14:30:00", "America/New_York"), "millisecond");
// "20240615-18:30:00.000"
```

A precision is accepted singular or plural, as `"millisecond"` or `"milliseconds"`. A name that is
neither returns `""`.

## Leap seconds

FIX allows a second of `60` and says it is for a UTC leap second only. Its own example is the
sequence that ended 1998:

```typescript
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

parseFixUtcTimestamp("19981231-23:59:59");
// { instant: "1998-12-31T23:59:59Z", precision: "second", leapSecond: false, picoseconds: 0 }
parseFixUtcTimestamp("19981231-23:59:60");
// { instant: "1998-12-31T23:59:60Z", precision: "second", leapSecond: true, picoseconds: 0 }
parseFixUtcTimestamp("19990101-00:00:00");
// { instant: "1999-01-01T00:00:00Z", precision: "second", leapSecond: false, picoseconds: 0 }
```

Only the 27 leap seconds UTC has inserted, the first at the end of June 1972 and the last at the
end of 2016, are real. A `60` on any other day returns `null`, and so does a leap second before
1972. [`isValidFixUtcTimestamp(value)`](/gmt/reference/finance/validate/isValidFixUtcTimestamp/) answers
the same question as a boolean, and is `true` exactly when the parser returns a value.

```typescript
import { isValidFixUtcTimestamp } from "@northguild/gmt/finance/validate";
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

isValidFixUtcTimestamp("20161231-23:59:60");
// true
isValidFixUtcTimestamp("20171231-23:59:60");
// false (no leap second was inserted that day)
parseFixUtcTimestamp("19720630-23:59:60");
// { instant: "1972-06-30T23:59:60Z", precision: "second", leapSecond: true, picoseconds: 0 }
parseFixUtcTimestamp("19710630-23:59:60");
// null
```

The instant of a leap second is written `…T23:59:60Z`, the way the rest of the library writes it. A
fraction carries through, and the formatter writes the leap second back:

```typescript
import { formatFixUtcTimestamp } from "@northguild/gmt/finance/format";
import { parseFixUtcTimestamp } from "@northguild/gmt/finance/parse";

parseFixUtcTimestamp("20161231-23:59:60.500");
// { instant: "2016-12-31T23:59:60.500Z", precision: "millisecond", leapSecond: true, picoseconds: 0 }
formatFixUtcTimestamp("2016-12-31T23:59:60.5Z", "millisecond");
// "20161231-23:59:60.500"
```

The instant reads back through the leap-second functions of `timescale/`, which are the ones that
accept a second of 60. [`toTAI`](/gmt/reference/timescale/convert/toTAI/) places it, and
[`isLeapSecond`](/gmt/reference/timescale/validate/isLeapSecond/) confirms it:

```typescript
import { toTAI } from "@northguild/gmt/timescale/convert";
import { isLeapSecond } from "@northguild/gmt/timescale/validate";

toTAI("2016-12-31T23:59:60Z");
// "2017-01-01T00:00:36 TAI"
isLeapSecond("2016-12-31T23:59:60Z");
// true
isLeapSecond("2017-12-31T23:59:60Z");
// false
```

A plain `Temporal.Instant.from` does not accept the second. It clamps `2016-12-31T23:59:60Z` to
`2016-12-31T23:59:59Z`, so the inserted second is stored as the one before it, and on a day with no
leap second it stores a second that never happened as a real one. Read the stamp with
`parseFixUtcTimestamp` first.

## Reading a SWIFT value date

A SWIFT value date is the date a payment takes effect. It is written `YYMMDD`: two digits for the
year, two for the month and two for the day. SWIFT describes the format as `<DATE2>`, or `6!n`
(six digits, exactly). It sits in field 30, and at the front of field 32A.

[`parseSwiftDate(value)`](/gmt/reference/finance/parse/parseSwiftDate/) reads bare digits and returns
the ISO date. It returns `""` for anything that is not a value date. A `:32A:` subfield also
holds a currency and an amount, so split it first and pass the date alone.

```typescript
import { parseSwiftDate } from "@northguild/gmt/finance/parse";

parseSwiftDate("240615");
// "2024-06-15"
parseSwiftDate("240615EUR1000,00");
// "" (the whole 32A subfield; pass the first six characters)
```

The rule applies where SWIFT states it: field 32A of MT 910, and fields 30 and 32A of category 1
and 2 messages, except the common group messages n92, n95 and n96. SWIFT states no century for
other six-digit dates, such as field 31D of MT 700. Read those with
[`parseDateWithPattern`](/gmt/reference/plain/parse/parseDateWithPattern/) and the `yearWindow` you
know.

## How a two-digit year gets its century

SWIFT's _Standards MT General Information_ (Standards MT November 2025) gives the rule. The year
of a value date is a `YY` from 01 to 60, read as 2001 to 2060. Any other `YY`, `00` and `61` to
`99` included, is not allowed: SWIFT answers it with error code T50. In SWIFT's words, from §6.3.1
Dates:

> The six-digit date thus ranges from 2001 to 2060

and, for value dates, from §6.3.6 Value Date Ordering:

> allowed: a year component … 'YY' in the range of 01 through 60
>
> not allowed: any 'YY' component outside of this range

| Digits | Century | Reads as  |
| ------ | ------- | --------- |
| 01–60  | 20YY    | 2001–2060 |
| 00     | none    | refused   |
| 61–99  | none    | refused   |

```typescript
import { parseSwiftDate } from "@northguild/gmt/finance/parse";

parseSwiftDate("010101");
// "2001-01-01"
parseSwiftDate("601231");
// "2060-12-31"
parseSwiftDate("000101");
// "" (YY 00 is not from 01 to 60)
parseSwiftDate("610101");
// "" (2061 is after 2060)
parseSwiftDate("990615");
// "" (YY 99 is not from 01 to 60, so it is not 1999 either)
```

The SSIM and EDI parsers ask you for a window. These functions take none, because the standard
mandates the rule: there is no choice to make. The
[Aviation guide](/gmt/guides/industries/aviation-message-times/) shows the windowed case.

The day must exist in the year the rule gives. `040229` is 29 February 2004, so it is accepted.
`050229` is 29 February 2005, which was not a leap year, so it is refused.

```typescript
import { parseSwiftDate } from "@northguild/gmt/finance/parse";

parseSwiftDate("040229");
// "2004-02-29"
parseSwiftDate("600229");
// "2060-02-29"
parseSwiftDate("050229");
// ""
```

## Writing a value date, and why the round trip refuses some years

[`formatSwiftDate(value)`](/gmt/reference/finance/format/formatSwiftDate/) takes an ISO date, such as
`2024-06-15`, and returns the six digits. It refuses a year the rule cannot read back. `2000-12-31`
and `2061-01-01` are outside 2001 to 2060. `1924-06-15` shows why the range matters: its last two
digits, `24`, would read back as 2024, a century later than the date you wrote. So it returns `""`.

```typescript
import { formatSwiftDate } from "@northguild/gmt/finance/format";

formatSwiftDate("2024-06-15");
// "240615"
formatSwiftDate("2001-01-01");
// "010101"
formatSwiftDate("2060-12-31");
// "601231"
formatSwiftDate("2000-12-31");
// ""
formatSwiftDate("2061-01-01");
// ""
formatSwiftDate("1924-06-15");
// ""
```

Every date the function writes reads back as the same date, written `YYYY-MM-DD`. So
`parseSwiftDate(formatSwiftDate(d)) === d` when `d` is already written that way.

The result is the date only. If you start from a date-time, take it to its date in the zone you
mean first. `formatSwiftDate("2024-06-15T10:00:00")` returns `""`.

[`isValidSwiftDate(value)`](/gmt/reference/finance/validate/isValidSwiftDate/) answers the reading
question as a boolean. It is `true` exactly when `parseSwiftDate` returns a date.

```typescript
import { isValidSwiftDate } from "@northguild/gmt/finance/validate";

isValidSwiftDate("240615");
// true
isValidSwiftDate("050229");
// false
isValidSwiftDate("750101");
// false
```

## See it break, then work

- [A Millisecond Stamp Read as Nanoseconds](/gmt/scenarios/a-millisecond-stamp-read-as-nanoseconds/)
- [Second Sixty on an Ordinary Day](/gmt/scenarios/second-sixty-on-an-ordinary-day/)
- [A Value Date in the Wrong Century](/gmt/scenarios/a-value-date-in-the-wrong-century/)
- [SWIFT Value Date Reader](/gmt/tools/swift-value-date-reader/)
- [Finance mistakes](/gmt/mistakes/finance/)

## Sources

- FIX Trading Community, FIX Latest, data type `UTCTimestamp` (read through the FIX Orchestra
  data-type browser): the format, the field ranges, a second of 60 only for a UTC leap second, the
  four named precisions, the bilateral-agreement clause and the 1998 leap-second example.
- ITU-R Recommendation TF.460-6: the inserted second is the one before a positive step, and it is
  written 23h 59m 60s.
- IERS, `Leap_Second.dat` and Bulletin C 72, for the 27 leap seconds.
- SWIFT, _Standards MT General Information_ (Standards MT November 2025, 18 July 2025), §6.3.1
  Dates (p. 44) and §6.3.6 Value Date Ordering (p. 59): the `YYMMDD` form, the 2001 to 2060
  range, `YY` from 01 to 60 and error code T50. It needs no login:
  [usgi_20250718.pdf](https://www2.swift.com/knowledgecentre/rest/v1/publications/usgi_20250718/2.0/usgi_20250718.pdf).
- SWIFT Standards MT (2015 User Handbook), MT 103 field 32A: the format `6!n3!a15d` and "Date must
  be a valid date expressed as YYMMDD". It is in SWIFT's Knowledge Centre, which needs a login.
