feat(perps): expose server time

.changeset/dev-466-perps-server-time.md

@@ -0,0 +1,6 @@
+---
+'@polymarket/bindings': minor
+'@polymarket/client': minor
+---
+
+Exposes the public Perps server clock.

packages/bindings/src/perps/market.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest';
 import {
+  GetServerTimeResponseSchema,
   PerpsFeeScheduleEntrySchema,
   PerpsFundingIntervalSchema,
   PerpsInstrumentSchema,
@@ -9,6 +10,20 @@ import {
 
 const txHash = `0x${'1'.repeat(64)}`;
 
+describe('GetServerTimeResponseSchema', () => {
+  it('parses an epoch-millisecond server time', () => {
+    expect(
+      GetServerTimeResponseSchema.parse({ time: 1_766_000_000_000 }),
+    ).toEqual({ time: 1_766_000_000_000 });
+  });
+
+  it('rejects a non-integer server time', () => {
+    expect(() =>
+      GetServerTimeResponseSchema.parse({ time: 1_766_000_000_000.5 }),
+    ).toThrow();
+  });
+});
+
 describe('PerpsFundingIntervalSchema', () => {
   it('accepts positive whole-hour funding intervals', () => {
     expect(PerpsFundingIntervalSchema.parse('1h')).toBe('1h');

packages/bindings/src/perps/market.ts

@@ -467,6 +467,13 @@ export type PerpsFeesInfo = z.infer<typeof PerpsFeesInfoSchema>;
  */
 export const FetchPerpsFeesResponseSchema = PerpsFeesInfoSchema;
 
+/**
+ * @experimental This API may change in a breaking way in any release, including patch releases.
+ */
+export const GetServerTimeResponseSchema = z.object({
+  time: EpochMillisecondsSchema,
+});
+
 /**
  * @experimental This API may change in a breaking way in any release, including patch releases.
  */

packages/client/src/actions/perps.test-d.ts

@@ -1,3 +1,4 @@
+import type { EpochMilliseconds } from '@polymarket/bindings';
 import { PerpsInstrumentCategory } from '@polymarket/bindings/perps';
 import { describe, expectTypeOf, it } from 'vitest';
 import type {
@@ -28,14 +29,19 @@ import type {
   PlacePerpsOrderWithTpSlRequest,
   PlacePerpsPositionTpSlRequest,
   PostPerpsOrdersRequest,
+  PublicPerpsActions,
   RevokePerpsCredentialsRequest,
   FetchPerpsInstrumentsRequest as RootFetchPerpsInstrumentsRequest,
   UpdatePerpsLeverageRequest,
   UpdatePerpsMarginRequest,
   WithdrawFromPerpsRequest,
 } from '../index';
-import { FetchPerpsTickerError, UpdatePerpsMarginError } from '../index';
-import type { FetchPerpsInstrumentsRequest } from './perps';
+import {
+  FetchPerpsTickerError,
+  GetServerTimeError,
+  UpdatePerpsMarginError,
+} from '../index';
+import type { FetchPerpsInstrumentsRequest, getServerTime } from './perps';
 
 describe('FetchPerpsInstrumentsRequest', () => {
   it('allows current instrument filters', () => {
@@ -57,6 +63,15 @@ describe('FetchPerpsInstrumentsRequest', () => {
 });
 
 describe('public Perps exports', () => {
+  it('exposes branded server time returns', () => {
+    expectTypeOf<ReturnType<typeof getServerTime>>().toEqualTypeOf<
+      Promise<EpochMilliseconds>
+    >();
+    expectTypeOf<
+      ReturnType<PublicPerpsActions['getServerTime']>
+    >().toEqualTypeOf<Promise<EpochMilliseconds>>();
+  });
+
   it('exports Perps request types from the root entry point', () => {
     expectTypeOf<RootFetchPerpsInstrumentsRequest>().toEqualTypeOf<FetchPerpsInstrumentsRequest>();
     expectTypeOf<FetchPerpsTickerRequest>().toEqualTypeOf<{
@@ -105,6 +120,7 @@ describe('public Perps exports', () => {
 
     expectTypeOf<RootPerpsSessionErrors>().toEqualTypeOf<RootPerpsSessionErrors>();
     void FetchPerpsTickerError;
+    void GetServerTimeError;
     void UpdatePerpsMarginError;
   });
 });

packages/client/src/actions/perps.test.ts

@@ -5,6 +5,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, it } from 'vitest';
 import type { BaseClient } from '../clients';
 import { ServiceClient } from '../ServiceClient';
 import {
+  getServerTime,
   listPerpsCandles,
   listPerpsFundingHistory,
   listPerpsTrades,
@@ -27,6 +28,30 @@ describe('Perps actions', () => {
     server.close();
   });
 
+  it('gets the server time from the public info endpoint', async () => {
+    const time = 1_766_000_000_000;
+    server.use(
+      http.get(`${root}/v1/info/time`, ({ request }) => {
+        expect(request.url).toBe(`${root}/v1/info/time`);
+        return HttpResponse.json({ time });
+      }),
+    );
+
+    await expect(getServerTime(createClient())).resolves.toBe(time);
+  });
+
+  it('rejects malformed server time responses', async () => {
+    server.use(
+      http.get(`${root}/v1/info/time`, () =>
+        HttpResponse.json({ time: 'not-a-timestamp' }),
+      ),
+    );
+
+    await expect(getServerTime(createClient())).rejects.toMatchObject({
+      name: 'UnexpectedResponseError',
+    });
+  });
+
   it('continues candle pages from the next interval boundary', async () => {
     const requests: URLSearchParams[] = [];
     server.use(

packages/client/src/actions/perps.ts

@@ -1,4 +1,5 @@
 import {
+  type EpochMilliseconds,
   type PaginationCursor,
   PaginationCursorSchema,
   toPaginationCursor,
@@ -12,6 +13,7 @@ import {
   FetchPerpsStatisticsResponseSchema,
   FetchPerpsTickersResponseSchema,
   FetchPerpsTradesResponseSchema,
+  GetServerTimeResponseSchema,
   type PerpsBook,
   PerpsBookSchema,
   type PerpsCandle,
@@ -793,6 +795,48 @@ export async function fetchPerpsFees(
   return response.feeSchedule;
 }
 
+/**
+ * @experimental This API may change in a breaking way in any release, including patch releases.
+ */
+export type GetServerTimeError =
+  | RateLimitError
+  | RequestRejectedError
+  | TransportError
+  | UnexpectedResponseError;
+/**
+ * @experimental This API may change in a breaking way in any release, including patch releases.
+ */
+export const GetServerTimeError = makeErrorGuard(
+  RateLimitError,
+  RequestRejectedError,
+  TransportError,
+  UnexpectedResponseError,
+);
+
+/**
+ * Gets the current Perps server time as a Unix timestamp in milliseconds.
+ *
+ * @remarks
+ * This is a low-level function. Most SDK consumers should prefer the client instance API.
+ * This read does not change how the SDK timestamps or signs Perps requests.
+ *
+ * @throws {@link GetServerTimeError}
+ * Thrown on failure.
+ *
+ * @experimental This API may change in a breaking way in any release, including patch releases.
+ */
+export async function getServerTime(
+  client: BaseClient,
+): Promise<EpochMilliseconds> {
+  const response = await unwrap(
+    client.perps
+      .get('/v1/info/time')
+      .andThen(validateWith(GetServerTimeResponseSchema)),
+  );
+
+  return response.time;
+}
+
 const PerpsCandlesCursorStateSchema = z.object({
   kind: z.literal('perpsCandles'),
   instrumentId: PerpsInstrumentIdSchema,

packages/client/src/decorators/perps.ts

@@ -1,3 +1,4 @@
+import type { EpochMilliseconds } from '@polymarket/bindings';
 import type {
   PerpsBook,
   PerpsCandle,
@@ -20,6 +21,7 @@ import {
   fetchPerpsInstruments,
   fetchPerpsTicker,
   fetchPerpsTickers,
+  getServerTime,
   type ListPerpsCandlesRequest,
   type ListPerpsFundingHistoryRequest,
   type ListPerpsTradesRequest,
@@ -108,6 +110,7 @@ export {
   FetchPerpsInstrumentsError,
   FetchPerpsTickerError,
   FetchPerpsTickersError,
+  GetServerTimeError,
   ListPerpsCandlesError,
   ListPerpsFundingHistoryError,
   ListPerpsTradesError,
@@ -258,6 +261,24 @@ export type PublicPerpsActions = {
    * @experimental This API may change in a breaking way in any release, including patch releases.
    */
   fetchPerpsFees(): Promise<PerpsFeeScheduleEntry[]>;
+
+  /**
+   * Gets the current Perps server time as a Unix timestamp in milliseconds.
+   *
+   * @remarks
+   * This read does not change how the SDK timestamps or signs Perps requests.
+   *
+   * @example
+   * ```ts
+   * const serverTime = await client.getServerTime();
+   * ```
+   *
+   * @throws {@link GetServerTimeError}
+   * Thrown on failure.
+   *
+   * @experimental This API may change in a breaking way in any release, including patch releases.
+   */
+  getServerTime(): Promise<EpochMilliseconds>;
 };
 
 /**
@@ -361,6 +382,7 @@ export function perpsActions(
     fetchPerpsInstruments: (request) => fetchPerpsInstruments(client, request),
     fetchPerpsTicker: (request) => fetchPerpsTicker(client, request),
     fetchPerpsTickers: (request) => fetchPerpsTickers(client, request),
+    getServerTime: () => getServerTime(client),
     listPerpsCandles: (request) => listPerpsCandles(client, request),
     listPerpsFundingHistory: (request) =>
       listPerpsFundingHistory(client, request),

packages/client/tests/integration/perps.test.ts

@@ -22,6 +22,7 @@ import {
 
 const DEFAULT_PERPS_CREDENTIAL_EXPIRES_IN = 7 * 24 * 60 * 60 * 1000;
 const MAX_PERPS_PRICE_SIGNIFICANT_FIGURES = 5;
+const MAX_SERVER_CLOCK_SKEW_MS = 60_000;
 
 const [instrument] = await publicClient
   .fetchPerpsInstruments()
@@ -31,6 +32,21 @@ const [ticker] = await publicClient
   .then(expectNonEmptyArray);
 
 describe('Perps integration', () => {
+  it('fetches the Perps server time in epoch milliseconds', async ({
+    publicClient,
+  }) => {
+    const startedAt = Date.now();
+    const serverTime = await publicClient.getServerTime();
+    const completedAt = Date.now();
+
+    expect(serverTime).toBeGreaterThanOrEqual(
+      startedAt - MAX_SERVER_CLOCK_SKEW_MS,
+    );
+    expect(serverTime).toBeLessThanOrEqual(
+      completedAt + MAX_SERVER_CLOCK_SKEW_MS,
+    );
+  });
+
   it.runIf(runMeteredTests)(
     'deposits and withdraws the same Perps amount',
     async ({ secureClientWithDepositWallet }) => {