@limitless-exchange/sdk 1.0.3 → 1.0.5

package/README.md

@@ -1,10 +1,10 @@
 # Limitless Exchange TypeScript SDK
 
-**v1.0.3** | Production-Ready | Type-Safe | Fully Documented
+**v1.0.5** | 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.3 Release**: Adds market-pages navigation API support, redirect-aware path resolution, and expanded typing parity. See [Changelog](#changelog) for details.
+> 🎉 **v1.0.5 Release**: Adds `FAK` limit-order support and `postOnly` for `GTC` orders, with updated docs and examples. See [Changelog](#changelog) for details.
 
 ## ⚠️ Disclaimer
 
@@ -41,6 +41,7 @@ For production use, we strongly recommend:
 - ✅ **NegRisk Markets**: Full support for group markets with multiple outcomes
 - ✅ **Error Handling & Retry**: Automatic retry logic for rate limits and transient failures
 - ✅ **Type Safety**: Full TypeScript support with comprehensive type definitions
+- ✅ **IEEE-Safe Order Payload Parsing**: `createOrder()` handles `makerAmount`, `takerAmount`, `price`, and `salt` returned as JSON strings
 - ✅ **TSDoc Documentation**: Complete API documentation with examples
 - ✅ **WebSocket**: Real-time price and position updates with API key auth
 
@@ -89,7 +90,7 @@ const page2 = await marketFetcher.getActiveMarkets({
 });
 ```
 
-See [examples/project-integration/src/active-markets.ts](./examples/project-integration/src/active-markets.ts) for more examples.
+See [examples/project-integration/src/active-markets.ts](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/examples/project-integration/src/active-markets.ts) for more examples.
 
 ### Market Pages & Navigation (No Authentication Required)
 
@@ -120,7 +121,7 @@ if ('pagination' in markets) {
 }
 ```
 
-Detailed guide: [docs/market-pages/README.md](./docs/market-pages/README.md)
+Detailed guide: [docs/market-pages/README.md](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/market-pages/README.md)
 
 ### Authentication
 
@@ -157,6 +158,21 @@ LIMITLESS_API_KEY=sk_live_your_api_key_here
 PRIVATE_KEY=0x...
 ```
 
+### Partner API Token v3 / HMAC Usage
+
+The SDK also supports partner-scoped HMAC credentials for api-token v3 workflows such as token self-service, partner-account creation, and delegated trading.
+
+Use HMAC credentials only in a backend or BFF service. Do not expose partner HMAC secrets in browser bundles, frontend environment variables, or client-side storage.
+
+Recommended setup:
+
+- Keep public market and market-page reads in the browser.
+- Store the real HMAC `tokenId` / `secret` on your backend.
+- Use this SDK server-side to sign partner-authenticated requests.
+- Expose only your own app-specific endpoints to the frontend.
+
+See [`docs/code-samples/api-key-v3/`](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/tree/main/limitless-exchange-sdk/docs/code-samples/api-key-v3) for the partner HMAC examples.
+
 ### Token Approvals
 
 **Important**: Before placing orders, you must approve tokens for the exchange contracts. This is a **one-time setup** per wallet.
@@ -220,7 +236,7 @@ if (market.negRiskRequestId) {
 }
 ```
 
-For complete examples, see [docs/code-samples/setup-approvals.ts](./docs/code-samples/setup-approvals.ts).
+For complete examples, see [docs/code-samples/setup-approvals.ts](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/code-samples/setup-approvals.ts).
 
 ### Trading on NegRisk Markets
 
@@ -256,7 +272,61 @@ const order = await orderClient.createOrder({
 
 **Important**: Always use the **submarket slug** for NegRisk orders, not the group market slug!
 
-For more details, see the [NegRisk Trading Guide](./docs/orders/README.md#negrisk-markets).
+For more details, see the [NegRisk Trading Guide](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/orders/README.md#negrisk-markets).
+
+### GTC Orders (Limit Orders)
+
+GTC orders use `price` + `size` and can optionally set `postOnly` to reject an order that would immediately match.
+
+```typescript
+import { OrderClient, Side, OrderType } from '@limitless-exchange/sdk';
+
+const gtcOrder = await orderClient.createOrder({
+  tokenId: marketDetails.tokens.yes,
+  price: 0.42,
+  size: 10,
+  side: Side.BUY,
+  orderType: OrderType.GTC,
+  marketSlug: 'market-slug',
+  postOnly: true, // Supported only for GTC
+});
+
+console.log(gtcOrder.order.id);
+```
+
+For complete examples, see [docs/code-samples/clob-gtc-order.ts](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/code-samples/clob-gtc-order.ts).
+
+### FAK Orders (Fill-and-Kill Limit Orders)
+
+FAK orders use the same `price` + `size` construction as `GTC`, but they only consume immediately available liquidity and cancel any remainder.
+
+```typescript
+import { OrderClient, Side, OrderType } from '@limitless-exchange/sdk';
+
+const fakOrder = await orderClient.createOrder({
+  tokenId: marketDetails.tokens.yes,
+  price: 0.45,
+  size: 10,
+  side: Side.BUY,
+  orderType: OrderType.FAK,
+  marketSlug: 'market-slug',
+});
+
+if (fakOrder.makerMatches && fakOrder.makerMatches.length > 0) {
+  console.log(`FAK matched immediately with ${fakOrder.makerMatches.length} fill(s)`);
+} else {
+  console.log('FAK remainder was cancelled.');
+}
+```
+
+**Key Differences from GTC**:
+
+- FAK uses `price` + `size` like GTC
+- Executes immediately up to the available size
+- Any unfilled remainder is cancelled
+- `postOnly` is not supported for FAK
+
+For complete examples, see [docs/code-samples/clob-fak-order.ts](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/code-samples/clob-fak-order.ts).
 
 ### FOK Orders (Fill-or-Kill Market Orders)
 
@@ -303,7 +373,7 @@ if (buyOrder.makerMatches && buyOrder.makerMatches.length > 0) {
 - All-or-nothing execution (no partial fills)
 - Best for immediate execution at market price
 
-For complete examples, see [docs/code-samples/clob-fok-order.ts](./docs/code-samples/clob-fok-order.ts).
+For complete examples, see [docs/code-samples/clob-fok-order.ts](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/code-samples/clob-fok-order.ts).
 
 ### Error Handling & Retry
 
@@ -343,7 +413,7 @@ class TradingService {
 - Callback hooks for monitoring retry attempts
 - Three approaches: decorator, wrapper function, or global client wrapper
 
-For detailed documentation, see the [Error Handling & Retry Guide](./docs/api/README.md).
+For detailed documentation, see the [Error Handling & Retry Guide](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/api/README.md).
 
 ## API Documentation
 
@@ -370,20 +440,20 @@ await httpClient.post('/endpoint', { data });
 
 ## Documentation
 
-For detailed documentation, see the [docs](./docs) directory:
+For detailed documentation, see the [docs](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/tree/main/limitless-exchange-sdk/docs) directory:
 
-- **[Complete Documentation](./docs/README.md)** - Full SDK documentation
-- **[Authentication Guide](./docs/api/README.md)** - API key authentication and HTTP client
-- **[Trading & Orders](./docs/orders/README.md)** - Order creation, management, and NegRisk markets
-- **[Market Data](./docs/markets/README.md)** - Market discovery and orderbook access
-- **[Portfolio & Positions](./docs/portfolio/README.md)** - Position tracking and user history
-- **[WebSocket Streaming](./docs/websocket/README.md)** - Real-time data updates
-- **[Error Handling & Retry](./docs/api/README.md)** - API error handling and retry mechanisms
-- **[Logging](./docs/logging/LOGGING.md)** - Logging configuration
+- **[Complete Documentation](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/README.md)** - Full SDK documentation
+- **[Authentication Guide](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/api/README.md)** - API key authentication and HTTP client
+- **[Trading & Orders](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/orders/README.md)** - Order creation, management, and NegRisk markets
+- **[Market Data](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/markets/README.md)** - Market discovery and orderbook access
+- **[Portfolio & Positions](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/portfolio/README.md)** - Position tracking and user history
+- **[WebSocket Streaming](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/websocket/README.md)** - Real-time data updates
+- **[Error Handling & Retry](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/api/README.md)** - API error handling and retry mechanisms
+- **[Logging](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/docs/logging/LOGGING.md)** - Logging configuration
 
 ## Code Examples
 
-Production-ready code samples are available in [docs/code-samples](./docs/code-samples):
+Production-ready code samples are available in [docs/code-samples](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/tree/main/limitless-exchange-sdk/docs/code-samples):
 
 ### Authentication Examples
 
@@ -397,24 +467,24 @@ Production-ready code samples are available in [docs/code-samples](./docs/code-s
 **CLOB Markets:**
 
 - `clob-fok-order.ts` - Fill-or-Kill market orders
-- `clob-gtc-order.ts` - Good-Til-Cancelled limit orders
+- `clob-gtc-order.ts` - Good-Til-Cancelled limit orders with `postOnly`
+- `clob-fak-order.ts` - Fill-And-Kill limit orders
 
 **NegRisk Markets:**
 
 - `negrisk-fok-order.ts` - FOK orders on group markets
-- `negrisk-gtc-trading-example.ts` - Complete NegRisk trading workflow
+- `negrisk-gtc-order.ts` - GTC orders on NegRisk submarkets
 
 ### Market Data Examples
 
 - `get-active-markets.ts` - Fetching active markets with sorting and pagination
 - `orderbook.ts` - Fetching and analyzing orderbooks
 - `positions.ts` - Portfolio and position tracking
-- `trading.ts` - Complete trading workflow
+- `fluent-api-trading-workflow.ts` - Complete trading workflow
 
 ### Real-Time Examples
 
-- `websocket-trading.ts` - Real-time order monitoring
-- `websocket-orderbook.ts` - Live orderbook streaming
+- `websocket-events.ts` - Real-time trading events and subscriptions
 
 ## Development
 
@@ -482,43 +552,45 @@ docs/
 
 ## Changelog
 
-### v1.0.3
+### v1.0.5
 
-**Release Date**: March 2026
+**Release Date**: April 2026
 
-Latest release with navigation-driven market discovery APIs and improved response/type parity.
+Latest release with `FAK` limit-order support and `postOnly` for `GTC` orders.
 
 #### Highlights
 
 - ✅ **Production-Ready**: Thoroughly tested and validated against Base mainnet
 - 🔒 **Type-Safe**: Full TypeScript support with comprehensive type definitions
-- 📚 **Well-Documented**: 17 production-ready code samples + comprehensive guides
+- 📚 **Well-Documented**: 18 production-ready code samples + comprehensive guides
 - ⚡ **Performance Optimized**: Venue caching system and connection pooling
 - 🔄 **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
+- 🧾 **More Trading Semantics**: `FAK` limit orders plus `postOnly` on `GTC`
 
 #### 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
+- **Order Management**: GTC, FAK, and FOK orders, GTC `postOnly`, tick alignment, automatic signing, IEEE-safe create-order payload parsing
 - **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.3)
+#### Documentation Enhancements (v1.0.5)
 
-- Added FOK order examples to README with clear `makerAmount` semantics
+- Added `FAK` order examples to README and code samples
+- Added `postOnly` usage to `GTC` examples and delegated-order samples
 - Created comprehensive CHANGELOG.md following Keep a Changelog format
-- All 17 code samples include step-by-step comments and error handling
+- All 18 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).
+For complete release notes, see [CHANGELOG.md](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/CHANGELOG.md).
 
 ---
 
@@ -532,4 +604,4 @@ For complete release notes, see [CHANGELOG.md](./CHANGELOG.md).
 
 ## License
 
-MIT - See [LICENSE](./LICENSE) file for details
+MIT - See [LICENSE](https://github.com/limitless-labs-group/limitless-exchange-ts-sdk/blob/main/limitless-exchange-sdk/LICENSE) file for details