@limitless-exchange/sdk 1.0.2 → 1.0.3

package/README.md

@@ -1,10 +1,10 @@
 # Limitless Exchange TypeScript SDK
 
-**v1.0.2 LTS (Long-Term Support)** | Production-Ready | Type-Safe | Fully Documented
+**v1.0.3** | Production-Ready | Type-Safe | Fully Documented
 
 A TypeScript SDK for interacting with the Limitless Exchange platform, providing type-safe access to CLOB and NegRisk prediction markets.
 
-> 🎉 **v1.0.2 LTS Release**: This is the first stable, production-ready release with long-term support. Recommended for all production deployments. See [Changelog](#changelog) for details.
+> 🎉 **v1.0.3 Release**: Adds market-pages navigation API support, redirect-aware path resolution, and expanded typing parity. See [Changelog](#changelog) for details.
 
 ## ⚠️ Disclaimer
 
@@ -91,6 +91,37 @@ const page2 = await marketFetcher.getActiveMarkets({
 
 See [examples/project-integration/src/active-markets.ts](./examples/project-integration/src/active-markets.ts) for more examples.
 
+### Market Pages & Navigation (No Authentication Required)
+
+```typescript
+import { HttpClient, MarketPageFetcher } from '@limitless-exchange/sdk';
+
+const httpClient = new HttpClient({
+  baseURL: 'https://api.limitless.exchange',
+});
+
+const pageFetcher = new MarketPageFetcher(httpClient);
+
+// Resolve a page from URL path
+const page = await pageFetcher.getMarketPageByPath('/crypto');
+
+// Fetch page markets with dynamic filters
+const markets = await pageFetcher.getMarkets(page.id, {
+  limit: 20,
+  sort: '-updatedAt',
+  filters: {
+    duration: 'hourly',
+    ticker: ['btc', 'eth'],
+  },
+});
+
+if ('pagination' in markets) {
+  console.log(`Total markets: ${markets.pagination.total}`);
+}
+```
+
+Detailed guide: [docs/market-pages/README.md](./docs/market-pages/README.md)
+
 ### Authentication
 
 The SDK uses API keys for authentication. API keys can be obtained from your Limitless Exchange account settings(Click on User Profile).
@@ -122,7 +153,7 @@ Create a `.env` file:
 # Required for authenticated endpoints
 LIMITLESS_API_KEY=sk_live_your_api_key_here
 
-# Optional: Private key for order signing (EIP-712)
+# REQUIRED: Private key for order signing (EIP-712)
 PRIVATE_KEY=0x...
 ```
 
@@ -325,7 +356,7 @@ HTTP client with API key authentication.
 ```typescript
 const httpClient = new HttpClient({
   baseURL: 'https://api.limitless.exchange',
-  apiKey: process.env.LIMITLESS_API_KEY, // Optional - auto-loads from env
+  apiKey: process.env.LIMITLESS_API_KEY, // you are allowed to pass it that way, otherwise will be loaded from .env
   timeout: 30000,
 });
 
@@ -451,11 +482,11 @@ docs/
 
 ## Changelog
 
-### v1.0.2 (LTS - Long-Term Support Release)
+### v1.0.3
 
-**Release Date**: January 2026
+**Release Date**: March 2026
 
-This is the first stable, production-ready release of the Limitless Exchange TypeScript SDK, designated as a Long-Term Support (LTS) version.
+Latest release with navigation-driven market discovery APIs and improved response/type parity.
 
 #### Highlights
 
@@ -466,23 +497,26 @@ This is the first stable, production-ready release of the Limitless Exchange Typ
 - 🔄 **Robust Error Handling**: Automatic retry logic with multiple strategies
 - 🌐 **Real-Time Updates**: WebSocket support for orderbook and position streaming
 - 🎯 **NegRisk Support**: Full support for group markets with multiple outcomes
+- 🧭 **Market Pages API**: Navigation tree, by-path resolver with 301 handling, page-scoped markets, property keys
 
 #### Core Features
 
 - **Authentication**: API key authentication, EIP-712 signing, EOA support
 - **Market Data**: Active markets with sorting, orderbook access, venue caching
+- **Market Pages & Navigation**: `/navigation`, `/market-pages/by-path`, `/market-pages/:id/markets`, `/property-keys`
 - **Order Management**: GTC and FOK orders, tick alignment, automatic signing
 - **Portfolio**: Position tracking, user history
 - **WebSocket**: Real-time orderbook, price updates, event streaming
 - **Error Handling**: Decorator and wrapper retry patterns, configurable strategies
 - **Token Approvals**: Complete setup script, CLOB and NegRisk workflows
 
-#### Documentation Enhancements (v1.0.2)
+#### Documentation Enhancements (v1.0.3)
 
 - Added FOK order examples to README with clear `makerAmount` semantics
 - Created comprehensive CHANGELOG.md following Keep a Changelog format
 - All 17 code samples include step-by-step comments and error handling
 - Detailed guides for authentication, trading, markets, portfolio, and WebSocket
+- Added market-pages guide and README quick-start for navigation-driven discovery
 
 For complete release notes, see [CHANGELOG.md](./CHANGELOG.md).
 
@@ -496,18 +530,6 @@ For complete release notes, see [CHANGELOG.md](./CHANGELOG.md).
 
 ---
 
-## LTS Support Policy
-
-**v1.0.2 LTS** will receive:
-
-- Security updates and critical bug fixes
-- Compatibility maintenance with Limitless Exchange API
-- Community support and issue resolution
-- Documentation updates and improvements
-- Long-term stability for production deployments
-
-**Recommended for production use.** We commit to maintaining backward compatibility and providing timely security updates for this LTS release.
-
 ## License
 
 MIT - See [LICENSE](./LICENSE) file for details

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AxiosRequestConfig } from 'axios';
+import { AxiosRequestConfig, RawAxiosResponseHeaders, AxiosResponseHeaders } from 'axios';
 import { ethers } from 'ethers';
 
 /**
@@ -1096,11 +1096,15 @@ interface MarketSettings {
     /**
      * Rewards epoch duration
      */
-    rewardsEpoch: string;
+    rewardsEpoch: string | number;
     /**
      * Constant parameter
      */
-    c: string;
+    c: string | number;
+    /**
+     * Market maker rebate rate.
+     */
+    rebateRate?: number;
 }
 /**
  * Trade prices for different order types.
@@ -1257,7 +1261,7 @@ interface Venue {
      * Required for NegRisk/Grouped markets only.
      * SELL orders on NegRisk markets require CT approval to both exchange AND adapter.
      */
-    adapter: string;
+    adapter: string | null;
 }
 /**
  * Market token IDs for CLOB markets.
@@ -1358,6 +1362,38 @@ interface Market$1 {
      * Formatted trading volume
      */
     volumeFormatted?: string;
+    /**
+     * Market automation type.
+     */
+    automationType?: 'manual' | 'lumy' | 'sports';
+    /**
+     * Primary market image URL.
+     */
+    imageUrl?: string | null;
+    /**
+     * Price trend data.
+     */
+    trends?: Record<string, unknown>;
+    /**
+     * Open interest (AMM markets).
+     */
+    openInterest?: string;
+    /**
+     * Formatted open interest (AMM markets).
+     */
+    openInterestFormatted?: string;
+    /**
+     * Liquidity (AMM markets).
+     */
+    liquidity?: string;
+    /**
+     * Formatted liquidity (AMM markets).
+     */
+    liquidityFormatted?: string;
+    /**
+     * Position IDs (AMM markets).
+     */
+    positionIds?: string[];
     /**
      * Condition ID (CLOB only)
      */
@@ -1897,6 +1933,28 @@ interface HttpClientConfig {
      */
     additionalHeaders?: Record<string, string>;
 }
+/**
+ * Raw HTTP response with status and headers.
+ *
+ * @remarks
+ * Useful for endpoints where response metadata matters (for example redirect handling).
+ *
+ * @public
+ */
+interface HttpRawResponse<T = any> {
+    /**
+     * HTTP status code.
+     */
+    status: number;
+    /**
+     * Response headers.
+     */
+    headers: RawAxiosResponseHeaders | AxiosResponseHeaders;
+    /**
+     * Response body.
+     */
+    data: T;
+}
 /**
  * HTTP client wrapper for Limitless Exchange API.
  *
@@ -1921,6 +1979,16 @@ declare class HttpClient {
      * @internal
      */
     private setupInterceptors;
+    /**
+     * Extracts a human-readable error message from API response payload.
+     * @internal
+     */
+    private extractErrorMessage;
+    /**
+     * Creates a typed API error class from status code.
+     * @internal
+     */
+    private createTypedApiError;
     /**
      * Sets the API key for authenticated requests.
      *
@@ -1939,6 +2007,17 @@ declare class HttpClient {
      * @returns Promise resolving to the response data
      */
     get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Performs a GET request and returns raw response metadata.
+     *
+     * @remarks
+     * Use this when callers need access to status code or headers (e.g. redirect `Location`).
+     *
+     * @param url - Request URL
+     * @param config - Additional request configuration
+     * @returns Promise resolving to status, headers, and response data
+     */
+    getRaw<T = any>(url: string, config?: AxiosRequestConfig): Promise<HttpRawResponse<T>>;
     /**
      * Performs a POST request.
      *
@@ -1998,6 +2077,14 @@ declare class Market {
     metadata: MarketMetadata;
     volume?: string;
     volumeFormatted?: string;
+    automationType?: 'manual' | 'lumy' | 'sports';
+    imageUrl?: string | null;
+    trends?: Record<string, unknown>;
+    openInterest?: string;
+    openInterestFormatted?: string;
+    liquidity?: string;
+    liquidityFormatted?: string;
+    positionIds?: string[];
     conditionId?: string;
     negRiskRequestId?: string | null;
     tokens?: MarketTokens;
@@ -2048,6 +2135,159 @@ declare class Market {
     getUserOrders(): Promise<any[]>;
 }
 
+/**
+ * Navigation node returned by /navigation endpoint.
+ * @public
+ */
+interface NavigationNode {
+    id: string;
+    name: string;
+    slug: string;
+    path: string;
+    icon?: string;
+    children: NavigationNode[];
+}
+/**
+ * Filter group option for market pages.
+ * @public
+ */
+interface FilterGroupOption {
+    label: string;
+    value: string;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Filter group for market pages.
+ * @public
+ */
+interface FilterGroup {
+    name?: string;
+    slug?: string;
+    allowMultiple?: boolean;
+    presentation?: string;
+    options?: FilterGroupOption[];
+    source?: Record<string, unknown>;
+}
+/**
+ * Breadcrumb item returned by /market-pages/by-path endpoint.
+ * @public
+ */
+interface BreadcrumbItem {
+    name: string;
+    slug: string;
+    path: string;
+}
+/**
+ * Market page data resolved by path.
+ * @public
+ */
+interface MarketPage {
+    id: string;
+    name: string;
+    slug: string;
+    fullPath: string;
+    description: string | null;
+    baseFilter: Record<string, unknown>;
+    filterGroups: FilterGroup[];
+    metadata: Record<string, unknown>;
+    breadcrumb: BreadcrumbItem[];
+}
+/**
+ * Property option returned by property-keys endpoints.
+ * @public
+ */
+interface PropertyOption {
+    id: string;
+    propertyKeyId: string;
+    value: string;
+    label: string;
+    sortOrder: number;
+    parentOptionId: string | null;
+    metadata: Record<string, unknown>;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Property key returned by property-keys endpoints.
+ * @public
+ */
+interface PropertyKey {
+    id: string;
+    name: string;
+    slug: string;
+    type: 'select' | 'multi-select';
+    metadata: Record<string, unknown>;
+    isSystem: boolean;
+    options?: PropertyOption[];
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Offset pagination metadata.
+ * @public
+ */
+interface OffsetPagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+}
+/**
+ * Cursor pagination metadata.
+ * @public
+ */
+interface CursorPagination {
+    nextCursor: string | null;
+}
+/**
+ * Sort field for market-pages market listing.
+ * @public
+ */
+type MarketPageSortField = 'createdAt' | 'updatedAt' | 'deadline' | 'id';
+/**
+ * Sort value for market-pages market listing.
+ * @public
+ */
+type MarketPageSort = MarketPageSortField | `-${MarketPageSortField}`;
+/**
+ * Query params for /market-pages/:id/markets endpoint.
+ * @public
+ */
+type MarketPageFilterPrimitive = string | number | boolean;
+type MarketPageFilterValue = MarketPageFilterPrimitive | MarketPageFilterPrimitive[];
+/**
+ * Query params for /market-pages/:id/markets endpoint.
+ * @public
+ */
+interface MarketPageMarketsParams {
+    page?: number;
+    limit?: number;
+    sort?: MarketPageSort;
+    cursor?: string;
+    filters?: Record<string, MarketPageFilterValue>;
+}
+/**
+ * Offset response for /market-pages/:id/markets endpoint.
+ * @public
+ */
+interface MarketPageMarketsOffsetResponse {
+    data: Market[];
+    pagination: OffsetPagination;
+}
+/**
+ * Cursor response for /market-pages/:id/markets endpoint.
+ * @public
+ */
+interface MarketPageMarketsCursorResponse {
+    data: Market[];
+    cursor: CursorPagination;
+}
+/**
+ * Union response for /market-pages/:id/markets endpoint.
+ * @public
+ */
+type MarketPageMarketsResponse = MarketPageMarketsOffsetResponse | MarketPageMarketsCursorResponse;
+
 /**
  * API error types for Limitless Exchange SDK.
  * @module api/errors
@@ -3187,6 +3427,57 @@ declare class OrderClient {
     get ownerId(): number | undefined;
 }
 
+/**
+ * Fetcher for market-pages and property-keys APIs.
+ *
+ * @remarks
+ * This class provides access to the new navigation-driven market discovery API.
+ *
+ * @public
+ */
+declare class MarketPageFetcher {
+    private httpClient;
+    private logger;
+    /**
+     * Creates a new market-pages fetcher.
+     *
+     * @param httpClient - HTTP client for API calls
+     * @param logger - Optional logger
+     */
+    constructor(httpClient: HttpClient, logger?: ILogger);
+    /**
+     * Gets the navigation tree.
+     */
+    getNavigation(): Promise<NavigationNode[]>;
+    /**
+     * Resolves a market page by path.
+     *
+     * @remarks
+     * Handles 301 redirects manually by re-requesting `/market-pages/by-path` with the
+     * redirected path value from `Location` header.
+     */
+    getMarketPageByPath(path: string): Promise<MarketPage>;
+    private getMarketPageByPathInternal;
+    private extractRedirectPath;
+    /**
+     * Gets markets for a market page with optional filtering and pagination.
+     */
+    getMarkets(pageId: string, params?: MarketPageMarketsParams): Promise<MarketPageMarketsResponse>;
+    /**
+     * Lists all property keys with options.
+     */
+    getPropertyKeys(): Promise<PropertyKey[]>;
+    /**
+     * Gets a single property key by ID.
+     */
+    getPropertyKey(id: string): Promise<PropertyKey>;
+    /**
+     * Lists options for a property key, optionally filtered by parent option ID.
+     */
+    getPropertyOptions(keyId: string, parentId?: string): Promise<PropertyOption[]>;
+    private stringifyFilterValue;
+}
+
 /**
  * Portfolio data fetcher for Limitless Exchange.
  * @module portfolio/fetcher
@@ -3530,4 +3821,4 @@ declare class WebSocketClient {
     private getChannelFromKey;
 }
 
-export { type AMMPosition, APIError, type ActiveMarketsParams, type ActiveMarketsResponse, type ActiveMarketsSortBy, type AmmPriceEntry, AuthenticationError, BASE_SEPOLIA_CHAIN_ID, type BaseOrderArgs, type CLOBPosition, CONTRACT_ADDRESSES, type CollateralToken, ConsoleLogger, type CreatedOrder, DEFAULT_API_URL, DEFAULT_CHAIN_ID, DEFAULT_WS_URL, type FOKOrderArgs, type FillEvent, type GTCOrderArgs, type HistoryEntry, type HistoryResponse, HttpClient, type HttpClientConfig, type ILogger, type LatestTrade, Market, type MarketCreator, MarketFetcher, type Market$1 as MarketInterface, type MarketMetadata, type MarketOutcome, type MarketSettings, type MarketTokens, type MarketUpdate, type MarketsResponse, type ModeInfo, type NewOrderPayload, type NewPriceData, NoOpLogger, type OrderArgs, type OrderBook, OrderBuilder, OrderClient, type OrderClientConfig, type OrderMatch, type OrderResponse, OrderSigner, type OrderSigningConfig, OrderType, type OrderUpdate, OrderValidationError, type OrderbookData, type OrderbookEntry, type OrderbookUpdate, PortfolioFetcher, type PortfolioPositionsResponse, type PortfolioSummary, type Position, type PositionMarket, type PositionSide, type PriceOracleMetadata, type PriceUpdate, RateLimitError, type ReferralData, RetryConfig, type RetryConfigOptions, RetryableClient, SIGNING_MESSAGE_TEMPLATE, Side, SignatureType, type SignedOrder, type SubscriptionChannel, type SubscriptionOptions, type TokenBalance, type TradeEvent, type TradePrices, type TradingMode, type TransactionEvent, type UnsignedOrder, type UserData, type UserProfile, type UserRank, ValidationError, type Venue, WebSocketClient, type WebSocketConfig, type WebSocketEvents, WebSocketState, ZERO_ADDRESS, getContractAddress, retryOnErrors, validateOrderArgs, validateSignedOrder, validateUnsignedOrder, withRetry };
+export { type AMMPosition, APIError, type ActiveMarketsParams, type ActiveMarketsResponse, type ActiveMarketsSortBy, type AmmPriceEntry, AuthenticationError, BASE_SEPOLIA_CHAIN_ID, type BaseOrderArgs, type BreadcrumbItem, type CLOBPosition, CONTRACT_ADDRESSES, type CollateralToken, ConsoleLogger, type CreatedOrder, type CursorPagination, DEFAULT_API_URL, DEFAULT_CHAIN_ID, DEFAULT_WS_URL, type FOKOrderArgs, type FillEvent, type FilterGroup, type FilterGroupOption, type GTCOrderArgs, type HistoryEntry, type HistoryResponse, HttpClient, type HttpClientConfig, type HttpRawResponse, type ILogger, type LatestTrade, Market, type MarketCreator, MarketFetcher, type Market$1 as MarketInterface, type MarketMetadata, type MarketOutcome, type MarketPage, MarketPageFetcher, type MarketPageFilterPrimitive, type MarketPageFilterValue, type MarketPageMarketsCursorResponse, type MarketPageMarketsOffsetResponse, type MarketPageMarketsParams, type MarketPageMarketsResponse, type MarketPageSort, type MarketPageSortField, type MarketSettings, type MarketTokens, type MarketUpdate, type MarketsResponse, type ModeInfo, type NavigationNode, type NewOrderPayload, type NewPriceData, NoOpLogger, type OffsetPagination, type OrderArgs, type OrderBook, OrderBuilder, OrderClient, type OrderClientConfig, type OrderMatch, type OrderResponse, OrderSigner, type OrderSigningConfig, OrderType, type OrderUpdate, OrderValidationError, type OrderbookData, type OrderbookEntry, type OrderbookUpdate, PortfolioFetcher, type PortfolioPositionsResponse, type PortfolioSummary, type Position, type PositionMarket, type PositionSide, type PriceOracleMetadata, type PriceUpdate, type PropertyKey, type PropertyOption, RateLimitError, type ReferralData, RetryConfig, type RetryConfigOptions, RetryableClient, SIGNING_MESSAGE_TEMPLATE, Side, SignatureType, type SignedOrder, type SubscriptionChannel, type SubscriptionOptions, type TokenBalance, type TradeEvent, type TradePrices, type TradingMode, type TransactionEvent, type UnsignedOrder, type UserData, type UserProfile, type UserRank, ValidationError, type Venue, WebSocketClient, type WebSocketConfig, type WebSocketEvents, WebSocketState, ZERO_ADDRESS, getContractAddress, retryOnErrors, validateOrderArgs, validateSignedOrder, validateUnsignedOrder, withRetry };