@basedone/core 0.2.8 → 0.3.1

package/dist/index.mjs

@@ -1,5 +1,5 @@
-export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantBusinessType, MerchantEcommerceClient, MerchantReturnPolicyType, MerchantStatus, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './chunk-NKSQEISP.mjs';
-export { AssetIdUtils, InstrumentClient } from './chunk-VBC6EQ7Q.mjs';
+export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantBusinessType, MerchantEcommerceClient, MerchantReturnPolicyType, MerchantStatus, ORDER_STATUS_TRANSITIONS, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, canCancelOrder, formatPrice, getBackoffDelay, getNextStatuses, getStatusColor, getStatusLabel, getStatusProgress, isPickupOrder, isRetryableError, isValidAddress, isValidEmail, parseError, requiresTrackingInfo, retryWithBackoff, shouldNotifyCustomer, sleep, truncateAddress, validateStatusTransition } from './chunk-35WGIB5F.mjs';
+export { AssetIdUtils, InstrumentClient } from './chunk-OZPAOG43.mjs';
 import Decimal, { Decimal as Decimal$1 } from 'decimal.js';
 import { signL1Action, signUserSignedAction } from '@nktkas/hyperliquid/signing';
 
@@ -544,6 +544,48 @@ var TESTNET_USDC_SPOT_TOKEN = {
   deployerTradingFeeShare: "0.0"
 };
 
+// lib/constants/admin.ts
+var SUPER_ADMINS = [
+  "did:privy:cmc3hycnb00pljs0m1z010geq",
+  "did:privy:cmc8w2ddl01rdju0nylb6rp1v",
+  "did:privy:cmc3oftiz005fjx0msox3xgey",
+  "did:privy:cmcbx7i4400q8l90mawdymaag",
+  "did:privy:cmctbwphs00vzjz0m3la3zm4c",
+  "did:privy:cmcblrplb009ol70mia13winn",
+  "did:privy:cmcd2bvft00w3l90ljeyb4wn6",
+  "did:privy:cmc4y13ka0119kv0nckvgla1u",
+  "did:privy:cmc8qc36g00c1l70nnutuscue",
+  "did:privy:cmc8f1tf9019zlh0myjpi420p",
+  "did:privy:cmc6bturg002ql80mhzqr1d76",
+  "did:privy:cmc8uyr4t01kljo0mk3unzjl3",
+  "did:privy:cmcke9v7h00yijy0o2a41nhms"
+];
+var ADMINS = [
+  "did:privy:cmgfcjt2y0024kz0cpymoqbmp",
+  // aayush
+  "did:privy:cmeqj8tsi01k6la0c3s7gsl6w",
+  // elroy
+  "did:privy:cmiwrno1i00cdl70c5ro13eyp",
+  // adele
+  "did:privy:cmkc0jyy200abji0d42a0syil",
+  // matthew
+  "did:privy:cmlgc2zjk005vjo0cct10trdl",
+  // marketing
+  "did:privy:cme2d56i90091i90bdhuyaj7e",
+  // jun
+  "did:privy:cmm4av80f00140cldz3uv7io2",
+  // shubit
+  "did:privy:cmcbndjjm02fvjr0mrs42yahs"
+  // zlace
+];
+var ALL_ADMINS = [...SUPER_ADMINS, ...ADMINS];
+var ADMIN_WALLETS = [
+  "0x0c7582A67B8B6AD04Ea404A6C2A06aAc9E0d4e7c",
+  "0xDec587aDD20A6447fF0b29D70E95b10b197b1283",
+  "0x3e83987019c4CE29680401b72F8b18A2dE3f8fe6",
+  "0x5446A5Bc711170d5197DE33D8C193487794f30C0"
+];
+
 // lib/meta/metadata.ts
 var ROOT_DEX = "hyperliquid";
 var formatPriceAndSize = ({
@@ -780,10 +822,139 @@ function getDexFromCollateralTokenSymbol(collateralTokenSymbol) {
 }
 
 // lib/hip3/market-info.ts
-async function getAllPerpsMeta(infoClient) {
+async function getPerpConciseAnnotations(infoClient) {
   return infoClient.transport.request("info", {
-    type: "allPerpMetas"
+    type: "perpConciseAnnotations"
+  });
+}
+function enrichAllPerpsMetaWithAnnotations(metas, annotations) {
+  const map = new Map(annotations);
+  return metas.map((meta) => ({
+    ...meta,
+    universe: meta.universe.map((u) => {
+      const ann = map.get(u.name);
+      if (!ann) return u;
+      return {
+        ...u,
+        ...ann.category != null && ann.category !== "" ? { category: ann.category } : {},
+        ...ann.displayName != null && ann.displayName !== "" ? { displayName: ann.displayName } : {},
+        ...ann.keywords != null && ann.keywords.length > 0 ? { keywords: ann.keywords } : {}
+      };
+    })
+  }));
+}
+async function getAllPerpsMeta(infoClient) {
+  const [metas, annotations] = await Promise.all([
+    infoClient.transport.request("info", {
+      type: "allPerpMetas"
+    }),
+    getPerpConciseAnnotations(infoClient).catch(() => {
+      return [];
+    })
+  ]);
+  if (!annotations.length) {
+    return metas;
+  }
+  return enrichAllPerpsMetaWithAnnotations(metas, annotations);
+}
+
+// lib/abstraction/types.ts
+var ABSTRACTION_MODE_TO_AGENT_CODE = {
+  disabled: "i",
+  unifiedAccount: "u",
+  portfolioMargin: "p"
+};
+var AGENT_CODE_TO_ABSTRACTION_MODE = {
+  i: "disabled",
+  u: "unifiedAccount",
+  p: "portfolioMargin"
+};
+var UserSetAbstractionTypes = {
+  "HyperliquidTransaction:UserSetAbstraction": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "user", type: "address" },
+    { name: "abstraction", type: "string" },
+    { name: "nonce", type: "uint64" }
+  ]
+};
+async function getUserAbstraction(client, user) {
+  return await client.transport.request("info", {
+    type: "userAbstraction",
+    user
   });
 }
+async function setUserAbstraction(client, abstraction, user) {
+  const nonce = Date.now();
+  const isTestnet = client.isTestnet;
+  const action = {
+    type: "userSetAbstraction",
+    hyperliquidChain: isTestnet ? "Testnet" : "Mainnet",
+    signatureChainId: isTestnet ? "0x66eee" : "0xa4b1",
+    user,
+    abstraction,
+    nonce
+  };
+  const signature = await signUserSignedAction({
+    wallet: client.wallet,
+    action,
+    types: UserSetAbstractionTypes
+  });
+  return await client.transport.request("exchange", {
+    action,
+    signature,
+    nonce: action.nonce
+  });
+}
+async function agentSetAbstraction(client, abstraction) {
+  const nonce = Date.now();
+  const code = ABSTRACTION_MODE_TO_AGENT_CODE[abstraction];
+  const action = {
+    type: "agentSetAbstraction",
+    abstraction: code
+  };
+  const signature = await signL1Action({
+    wallet: client.wallet,
+    action,
+    isTestnet: client.isTestnet,
+    nonce
+  });
+  return await client.transport.request("exchange", {
+    action,
+    signature,
+    nonce
+  });
+}
+
+// lib/abstraction/ratio.ts
+function computeUnifiedAccountRatio(multiverse, perpDexStates, spotBalances) {
+  const indexToCollateralToken = {};
+  for (const meta of Object.values(multiverse)) {
+    indexToCollateralToken[meta.index] = meta.collateralToken;
+  }
+  const crossMarginByToken = {};
+  const isolatedMarginByToken = {};
+  for (let index = 0; index < perpDexStates.length; index++) {
+    const dex = perpDexStates[index];
+    const token = indexToCollateralToken[index];
+    if (dex === void 0 || token === void 0) continue;
+    crossMarginByToken[token] = (crossMarginByToken[token] ?? 0) + dex.clearinghouseState.crossMaintenanceMarginUsed;
+    for (const ap of dex.clearinghouseState.assetPositions) {
+      if (ap.position.leverage.type === "isolated") {
+        isolatedMarginByToken[token] = (isolatedMarginByToken[token] ?? 0) + ap.position.marginUsed;
+      }
+    }
+  }
+  let maxRatio = 0;
+  for (const [tokenStr, crossMargin] of Object.entries(crossMarginByToken)) {
+    const token = Number(tokenStr);
+    const spotTotal = spotBalances.find((b) => b.token === token)?.total ?? 0;
+    const isolatedMargin = isolatedMarginByToken[token] ?? 0;
+    const available = spotTotal - isolatedMargin;
+    if (available > 0) {
+      maxRatio = Math.max(maxRatio, crossMargin / available);
+    }
+  }
+  return maxRatio;
+}
 
-export { CloidClientCode, CloidClientCodeNameById, DayOfWeek, PUP_TOKEN_ADDRESS, PUP_TOKEN_THRESHOLDS, ROOT_DEX, TARGET_APPROVED_MAX_BUILDER_FEE, TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT, TESTNET_USDC_SPOT_TOKEN, USDC_SPOT_TOKEN, UserDexAbstractionTypes, WidgetType, WidgetTypeById, XP_BOOST_PERCENTAGES, buildCloid, calculateBoostPercentage, calculateTotalPupAmount, decodeSlug, enableHip3DexAbstractionWithAgent, encodeSlug, floorUtcDay, floorUtcHour, floorUtcMinutes, floorUtcWeek, formatPriceAndSize, formatPriceForDisplay, formatPriceForOrder, formatSizeForDisplay, formatSizeForOrder, getAllPerpsMeta, getApprovalAmount, getClientCodeNameById, getCloid, getDexFromCollateralTokenSymbol, getDisplayMarketSymbol, getHip3Dex, getHip3DexAbstraction, getLatestCompletedWeek, getNextTierInfo, getPriceDecimals, getStaticCollateralTokenByDex, getStaticCollateralTokenSymbol, getWeekInfoFromNumber, getWidgetTypeById, isBasedCloid, isClientCode, isHip3Symbol, isMiniAppCloid, isMiniAppTriggeredCloid, isSpotSymbol, isStableQuoteToken, isTenantCloid, isTrackingIdCloid, isWidgetType, makeUtcRounder, normaliseSlug, normaliseTrackingId, normalizeAirdropAmount, parseCloid, setHip3DexAbstraction, stableQuoteTokens };
+export { ABSTRACTION_MODE_TO_AGENT_CODE, ADMINS, ADMIN_WALLETS, AGENT_CODE_TO_ABSTRACTION_MODE, ALL_ADMINS, CloidClientCode, CloidClientCodeNameById, DayOfWeek, PUP_TOKEN_ADDRESS, PUP_TOKEN_THRESHOLDS, ROOT_DEX, SUPER_ADMINS, TARGET_APPROVED_MAX_BUILDER_FEE, TARGET_APPROVED_MAX_BUILDER_FEE_PERCENT, TESTNET_USDC_SPOT_TOKEN, USDC_SPOT_TOKEN, UserDexAbstractionTypes, UserSetAbstractionTypes, WidgetType, WidgetTypeById, XP_BOOST_PERCENTAGES, agentSetAbstraction, buildCloid, calculateBoostPercentage, calculateTotalPupAmount, computeUnifiedAccountRatio, decodeSlug, enableHip3DexAbstractionWithAgent, encodeSlug, enrichAllPerpsMetaWithAnnotations, floorUtcDay, floorUtcHour, floorUtcMinutes, floorUtcWeek, formatPriceAndSize, formatPriceForDisplay, formatPriceForOrder, formatSizeForDisplay, formatSizeForOrder, getAllPerpsMeta, getApprovalAmount, getClientCodeNameById, getCloid, getDexFromCollateralTokenSymbol, getDisplayMarketSymbol, getHip3Dex, getHip3DexAbstraction, getLatestCompletedWeek, getNextTierInfo, getPerpConciseAnnotations, getPriceDecimals, getStaticCollateralTokenByDex, getStaticCollateralTokenSymbol, getUserAbstraction, getWeekInfoFromNumber, getWidgetTypeById, isBasedCloid, isClientCode, isHip3Symbol, isMiniAppCloid, isMiniAppTriggeredCloid, isSpotSymbol, isStableQuoteToken, isTenantCloid, isTrackingIdCloid, isWidgetType, makeUtcRounder, normaliseSlug, normaliseTrackingId, normalizeAirdropAmount, parseCloid, setHip3DexAbstraction, setUserAbstraction, stableQuoteTokens };

package/dist/react.d.mts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import { SpotMeta } from '@nktkas/hyperliquid';
-import { A as AllPerpsMeta, I as InstrumentClient } from './client-DMVXX1Gw.mjs';
+import { A as AllPerpsMeta, I as InstrumentClient } from './client-1sWFpTpK.mjs';
 
 interface InstrumentsProviderProps {
     spotMeta: SpotMeta;

package/dist/react.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import { ReactNode } from 'react';
 import { SpotMeta } from '@nktkas/hyperliquid';
-import { A as AllPerpsMeta, I as InstrumentClient } from './client-DMVXX1Gw.js';
+import { A as AllPerpsMeta, I as InstrumentClient } from './client-1sWFpTpK.js';
 
 interface InstrumentsProviderProps {
     spotMeta: SpotMeta;

package/dist/react.js

@@ -188,7 +188,10 @@ var InstrumentClient = class {
           type: "futures",
           isDelisted: info.isDelisted,
           dex: AssetIdUtils.extractDexName(info.name),
-          collateralTokenIndex: perpMeta.collateralToken
+          collateralTokenIndex: perpMeta.collateralToken,
+          category: info.category,
+          displayName: info.displayName,
+          keywords: info.keywords
         };
         this.addInstrument(instrument);
       }

package/dist/react.mjs

@@ -1,4 +1,4 @@
-import { InstrumentClient } from './chunk-VBC6EQ7Q.mjs';
+import { InstrumentClient } from './chunk-OZPAOG43.mjs';
 import { createContext, useMemo, useContext } from 'react';
 import { jsx } from 'react/jsx-runtime';
 

package/index.ts

@@ -2,13 +2,16 @@ export * from "./lib/cloid/cloid";
 export * from "./lib/fee";
 export * from "./lib/pup";
 export * from "./lib/constants/tokens";
+export * from "./lib/constants/admin";
 export * from "./lib/meta/metadata";
 export * from "./lib/utils/formatter";
 export * from "./lib/utils/flooredDateTime";
 export * from "./lib/utils/time";
 export * from "./lib/hip3/utils";
 export * from "./lib/hip3/market-info";
+export * from "./lib/abstraction";
 export * from "./lib/instrument/client";
+export * from "./lib/types";
 
 // Ecommerce SDK
 export * from "./lib/ecommerce";

package/lib/abstraction/api.ts

@@ -0,0 +1,106 @@
+import {
+  ExchangeClient,
+  InfoClient,
+  SuccessResponse,
+} from "@nktkas/hyperliquid";
+import {
+  signL1Action,
+  signUserSignedAction,
+} from "@nktkas/hyperliquid/signing";
+import type {
+  UserAbstractionMode,
+  SettableAbstractionMode,
+  AgentAbstractionCode,
+} from "./types";
+import { ABSTRACTION_MODE_TO_AGENT_CODE } from "./types";
+
+export const UserSetAbstractionTypes = {
+  "HyperliquidTransaction:UserSetAbstraction": [
+    { name: "hyperliquidChain", type: "string" },
+    { name: "user", type: "address" },
+    { name: "abstraction", type: "string" },
+    { name: "nonce", type: "uint64" },
+  ],
+};
+
+/**
+ * Query a user's current account abstraction mode.
+ */
+export async function getUserAbstraction(
+  client: InfoClient,
+  user: string,
+): Promise<UserAbstractionMode> {
+  return await client.transport.request<UserAbstractionMode>("info", {
+    type: "userAbstraction",
+    user,
+  });
+}
+
+/**
+ * Set account abstraction mode using the owner wallet (user-signed action).
+ *
+ * Requires EIP-712 signature from the account owner.
+ */
+export async function setUserAbstraction(
+  client: ExchangeClient,
+  abstraction: SettableAbstractionMode,
+  user: string,
+): Promise<SuccessResponse> {
+  const nonce = Date.now();
+  const isTestnet = client.isTestnet;
+
+  const action = {
+    type: "userSetAbstraction" as const,
+    hyperliquidChain: isTestnet ? "Testnet" : ("Mainnet" as string),
+    signatureChainId: isTestnet
+      ? ("0x66eee" as `0x${string}`)
+      : ("0xa4b1" as `0x${string}`),
+    user,
+    abstraction,
+    nonce,
+  };
+
+  const signature = await signUserSignedAction({
+    wallet: client.wallet,
+    action,
+    types: UserSetAbstractionTypes,
+  });
+
+  return await client.transport.request<SuccessResponse>("exchange", {
+    action,
+    signature,
+    nonce: action.nonce,
+  });
+}
+
+/**
+ * Set account abstraction mode using an agent wallet.
+ *
+ * Uses shorthand codes: "i" (disabled), "u" (unifiedAccount), "p" (portfolioMargin).
+ */
+export async function agentSetAbstraction(
+  client: ExchangeClient,
+  abstraction: SettableAbstractionMode,
+): Promise<SuccessResponse> {
+  const nonce = Date.now();
+  const code: AgentAbstractionCode =
+    ABSTRACTION_MODE_TO_AGENT_CODE[abstraction];
+
+  const action = {
+    type: "agentSetAbstraction" as const,
+    abstraction: code,
+  };
+
+  const signature = await signL1Action({
+    wallet: client.wallet,
+    action,
+    isTestnet: client.isTestnet,
+    nonce,
+  });
+
+  return await client.transport.request<SuccessResponse>("exchange", {
+    action,
+    signature,
+    nonce,
+  });
+}

package/lib/abstraction/index.ts

@@ -0,0 +1,3 @@
+export * from "./types";
+export * from "./api";
+export * from "./ratio";

package/lib/abstraction/ratio.ts

@@ -0,0 +1,61 @@
+import type {
+  MultiverseMeta,
+  PerpDexClearinghouseState,
+  SpotBalance,
+} from "./types";
+
+/**
+ * Compute the unified account ratio for monitoring liquidation risk.
+ *
+ * The ratio represents cross maintenance margin used / available balance
+ * for the most leveraged collateral token. A higher ratio means closer
+ * to liquidation.
+ *
+ * @param multiverse - Map of DEX name to its metadata (index and collateral token)
+ * @param perpDexStates - Array of per-DEX clearinghouse states
+ * @param spotBalances - Array of spot balances per token
+ * @returns The maximum ratio across all collateral tokens (0 if no margin used)
+ */
+export function computeUnifiedAccountRatio(
+  multiverse: Record<string, MultiverseMeta>,
+  perpDexStates: PerpDexClearinghouseState[],
+  spotBalances: SpotBalance[],
+): number {
+  const indexToCollateralToken: Record<number, number> = {};
+  for (const meta of Object.values(multiverse)) {
+    indexToCollateralToken[meta.index] = meta.collateralToken;
+  }
+
+  const crossMarginByToken: Record<number, number> = {};
+  const isolatedMarginByToken: Record<number, number> = {};
+
+  for (let index = 0; index < perpDexStates.length; index++) {
+    const dex = perpDexStates[index];
+    const token = indexToCollateralToken[index];
+    if (dex === undefined || token === undefined) continue;
+
+    crossMarginByToken[token] =
+      (crossMarginByToken[token] ?? 0) +
+      dex.clearinghouseState.crossMaintenanceMarginUsed;
+
+    for (const ap of dex.clearinghouseState.assetPositions) {
+      if (ap.position.leverage.type === "isolated") {
+        isolatedMarginByToken[token] =
+          (isolatedMarginByToken[token] ?? 0) + ap.position.marginUsed;
+      }
+    }
+  }
+
+  let maxRatio = 0;
+  for (const [tokenStr, crossMargin] of Object.entries(crossMarginByToken)) {
+    const token = Number(tokenStr);
+    const spotTotal = spotBalances.find((b) => b.token === token)?.total ?? 0;
+    const isolatedMargin = isolatedMarginByToken[token] ?? 0;
+    const available = spotTotal - isolatedMargin;
+    if (available > 0) {
+      maxRatio = Math.max(maxRatio, crossMargin / available);
+    }
+  }
+
+  return maxRatio;
+}

package/lib/abstraction/types.ts

@@ -0,0 +1,73 @@
+/**
+ * User abstraction modes for controlling how spot and perps balances interact.
+ *
+ * - `disabled` (Standard): Separate perp and spot balances, separate DEX balances.
+ * - `unifiedAccount`: Single balance per asset collateralizing all cross margin positions.
+ * - `portfolioMargin`: Single portfolio unifying all eligible assets (pre-alpha).
+ * - `dexAbstraction`: Legacy mode (to be discontinued).
+ * - `default`: Server default (equivalent to standard/disabled for most users).
+ */
+export type UserAbstractionMode =
+  | "unifiedAccount"
+  | "portfolioMargin"
+  | "disabled"
+  | "default"
+  | "dexAbstraction";
+
+/**
+ * Shorthand codes used with agent-based abstraction setting.
+ * - `i` = disabled (standard)
+ * - `u` = unifiedAccount
+ * - `p` = portfolioMargin
+ */
+export type AgentAbstractionCode = "i" | "u" | "p";
+
+/**
+ * Settable abstraction modes (excludes read-only states like "default" and "dexAbstraction").
+ */
+export type SettableAbstractionMode =
+  | "disabled"
+  | "unifiedAccount"
+  | "portfolioMargin";
+
+export const ABSTRACTION_MODE_TO_AGENT_CODE: Record<
+  SettableAbstractionMode,
+  AgentAbstractionCode
+> = {
+  disabled: "i",
+  unifiedAccount: "u",
+  portfolioMargin: "p",
+};
+
+export const AGENT_CODE_TO_ABSTRACTION_MODE: Record<
+  AgentAbstractionCode,
+  SettableAbstractionMode
+> = {
+  i: "disabled",
+  u: "unifiedAccount",
+  p: "portfolioMargin",
+};
+
+export interface MultiverseMeta {
+  index: number;
+  collateralToken: number;
+}
+
+export interface PerpDexAssetPosition {
+  position: {
+    leverage: { type: string };
+    marginUsed: number;
+  };
+}
+
+export interface PerpDexClearinghouseState {
+  clearinghouseState: {
+    crossMaintenanceMarginUsed: number;
+    assetPositions: PerpDexAssetPosition[];
+  };
+}
+
+export interface SpotBalance {
+  token: number;
+  total: number;
+}

package/lib/constants/admin.ts

@@ -0,0 +1,39 @@
+// Super admin Privy user IDs — full unrestricted access
+export const SUPER_ADMINS = [
+  "did:privy:cmc3hycnb00pljs0m1z010geq",
+  "did:privy:cmc8w2ddl01rdju0nylb6rp1v",
+  "did:privy:cmc3oftiz005fjx0msox3xgey",
+  "did:privy:cmcbx7i4400q8l90mawdymaag",
+  "did:privy:cmctbwphs00vzjz0m3la3zm4c",
+  "did:privy:cmcblrplb009ol70mia13winn",
+  "did:privy:cmcd2bvft00w3l90ljeyb4wn6",
+  "did:privy:cmc4y13ka0119kv0nckvgla1u",
+  "did:privy:cmc8qc36g00c1l70nnutuscue",
+  "did:privy:cmc8f1tf9019zlh0myjpi420p",
+  "did:privy:cmc6bturg002ql80mhzqr1d76",
+  "did:privy:cmc8uyr4t01kljo0mk3unzjl3",
+  "did:privy:cmcke9v7h00yijy0o2a41nhms",
+];
+
+// Regular admin Privy user IDs — restricted access (no payouts/airdrops/launchpads/API keys/cache)
+export const ADMINS = [
+  "did:privy:cmgfcjt2y0024kz0cpymoqbmp", // aayush
+  "did:privy:cmeqj8tsi01k6la0c3s7gsl6w", // elroy
+  "did:privy:cmiwrno1i00cdl70c5ro13eyp", // adele
+  "did:privy:cmkc0jyy200abji0d42a0syil", // matthew
+  "did:privy:cmlgc2zjk005vjo0cct10trdl", // marketing
+  "did:privy:cme2d56i90091i90bdhuyaj7e", // jun
+  "did:privy:cmm4av80f00140cldz3uv7io2", // shubit
+  "did:privy:cmcbndjjm02fvjr0mrs42yahs", // zlace
+];
+
+// All admin IDs combined — use for "is this user any kind of admin?" checks
+export const ALL_ADMINS = [...SUPER_ADMINS, ...ADMINS];
+
+// Global admin wallet addresses
+export const ADMIN_WALLETS: string[] = [
+  "0x0c7582A67B8B6AD04Ea404A6C2A06aAc9E0d4e7c",
+  "0xDec587aDD20A6447fF0b29D70E95b10b197b1283",
+  "0x3e83987019c4CE29680401b72F8b18A2dE3f8fe6",
+  "0x5446A5Bc711170d5197DE33D8C193487794f30C0",
+];

package/lib/ecommerce/client/customer.ts

@@ -68,6 +68,8 @@ import type {
   GetExpiringGemsResponse,
   CashAccountBalanceResponse,
   DeliveryAddressResponse,
+  CustomerNotificationsResponse,
+  MarkNotificationsReadResponse,
 } from "../types";
 
 /**
@@ -1110,4 +1112,44 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async getDeliveryAddress(): Promise<DeliveryAddressResponse> {
     return this.get("/api/basedpay/delivery-address");
   }
+
+  /**
+   * Get user's Hyperliquid USDC balance (perp withdrawable)
+   *
+   * Returns the USDC balance available for escrow deposits via usdSend.
+   *
+   * @returns Balance response with amount and currency
+   */
+  async getUsdcBalance(): Promise<CashAccountBalanceResponse> {
+    return this.get("/api/marketplace/usdc-balance");
+  }
+
+  // ============================================================================
+  // Notifications API
+  // ============================================================================
+
+  /**
+   * List notifications for the authenticated customer
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Paginated list of notifications with unread count
+   */
+  async listNotifications(params?: {
+    limit?: number;
+    offset?: number;
+    unreadOnly?: boolean;
+  }): Promise<CustomerNotificationsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/notifications${queryString}`);
+  }
+
+  /**
+   * Mark notifications as read
+   *
+   * @param ids - Specific notification IDs to mark as read. If omitted, marks all as read.
+   * @returns Count of updated notifications
+   */
+  async markNotificationsAsRead(ids?: string[]): Promise<MarkNotificationsReadResponse> {
+    return this.patch("/api/marketplace/notifications/read", { ids });
+  }
 }

package/lib/ecommerce/index.ts

@@ -46,6 +46,20 @@ export {
   calculateFinalPrice,
 } from "./utils/helpers";
 
+// Export order state machine
+export {
+  ORDER_STATUS_TRANSITIONS,
+  validateStatusTransition,
+  getNextStatuses,
+  isPickupOrder,
+  getStatusLabel,
+  getStatusColor,
+  canCancelOrder,
+  requiresTrackingInfo,
+  shouldNotifyCustomer,
+  getStatusProgress,
+} from "./utils/orderStateMachine";
+
 // Export client config type
 export type { EcommerceClientConfig } from "./client/base";
 

package/lib/ecommerce/types/entities.ts

@@ -357,6 +357,20 @@ export interface Order extends BaseEntity {
   };
   /** Order events */
   events?: OrderEvent[];
+  /** Expected ship date */
+  expectedShipDate?: string | null;
+  /** Estimated delivery date */
+  estimatedDeliveryDate?: string | null;
+  /** Estimated delivery days */
+  estimatedDeliveryDays?: number | null;
+  /** Auto-complete deadline */
+  autoCompleteDeadline?: string | null;
+  /** Customer confirmed receipt timestamp */
+  customerConfirmedAt?: string | null;
+  /** Auto-completed timestamp */
+  autoCompletedAt?: string | null;
+  /** Status transition timestamps */
+  statusTransitions?: Record<string, string> | null;
 }
 
 /**

package/lib/ecommerce/types/enums.ts

@@ -22,6 +22,8 @@ export enum OrderStatus {
   DELIVERED = "DELIVERED",
   /** Order has been cancelled */
   CANCELLED = "CANCELLED",
+  /** Payment settled / escrow released to merchant */
+  SETTLED = "SETTLED",
   /** Order is confirmed (legacy status) */
   CONFIRMED = "CONFIRMED",
   /** Order is completed (legacy status) */
@@ -286,8 +288,10 @@ export enum ProductSortBy {
   PRICE_ASC = "price_asc",
   /** Sort by price (high to low) */
   PRICE_DESC = "price_desc",
-  /** Sort by popularity */
+  /** Sort by popularity (views) */
   POPULAR = "popular",
+  /** Sort by best selling (sold quantity) */
+  BEST_SELLING = "best_selling",
   /** Sort by featured status */
   FEATURED = "featured",
   /** Sort by proximity to user location (requires lat/lng) */