@0xarchive/sdk 0.4.0 → 0.4.2

package/README.md

@@ -4,7 +4,7 @@ Official TypeScript/JavaScript SDK for [0xarchive](https://0xarchive.io) - Histo
 
 Supports multiple exchanges:
 - **Hyperliquid** - Perpetuals data from April 2023
-- **Lighter.xyz** - Perpetuals data with orderbook reconstruction
+- **Lighter.xyz** - Perpetuals data (August 2025+ for fills, Jan 2026+ for OB, OI, Funding Rate)
 
 ## Installation
 
@@ -108,13 +108,39 @@ while (result.nextCursor) {
 ### Instruments
 
 ```typescript
-// List all trading instruments
+// List all trading instruments (Hyperliquid)
 const instruments = await client.hyperliquid.instruments.list();
 
 // Get specific instrument details
 const btc = await client.hyperliquid.instruments.get('BTC');
+console.log(`BTC size decimals: ${btc.szDecimals}`);
 ```
 
+#### Lighter.xyz Instruments
+
+Lighter instruments have a different schema with additional fields for fees, market IDs, and minimum order amounts:
+
+```typescript
+// List Lighter instruments (returns LighterInstrument, not Instrument)
+const lighterInstruments = await client.lighter.instruments.list();
+
+// Get specific Lighter instrument
+const eth = await client.lighter.instruments.get('ETH');
+console.log(`ETH taker fee: ${eth.takerFee}`);
+console.log(`ETH maker fee: ${eth.makerFee}`);
+console.log(`ETH market ID: ${eth.marketId}`);
+console.log(`ETH min base amount: ${eth.minBaseAmount}`);
+```
+
+**Key differences:**
+| Field | Hyperliquid (`Instrument`) | Lighter (`LighterInstrument`) |
+|-------|---------------------------|------------------------------|
+| Symbol | `name` | `symbol` |
+| Size decimals | `szDecimals` | `sizeDecimals` |
+| Fee info | Not available | `takerFee`, `makerFee`, `liquidationFee` |
+| Market ID | Not available | `marketId` |
+| Min amounts | Not available | `minBaseAmount`, `minQuoteAmount` |
+
 ### Funding Rates
 
 ```typescript
@@ -350,6 +376,7 @@ import type {
   PriceLevel,
   Trade,
   Instrument,
+  LighterInstrument,
   FundingRate,
   OpenInterest,
   CursorResponse,

package/dist/index.d.mts

@@ -148,7 +148,7 @@ interface CursorResponse<T> {
 /** Instrument type */
 type InstrumentType = 'perp' | 'spot';
 /**
- * Trading instrument metadata
+ * Trading instrument metadata (Hyperliquid)
  */
 interface Instrument {
     /** Instrument symbol (e.g., BTC) */
@@ -164,6 +164,40 @@ interface Instrument {
     /** Whether the instrument is currently tradeable */
     isActive: boolean;
 }
+/**
+ * Trading instrument metadata (Lighter.xyz)
+ *
+ * Lighter instruments have a different schema than Hyperliquid with more
+ * detailed market configuration including fees and minimum amounts.
+ */
+interface LighterInstrument {
+    /** Instrument symbol (e.g., BTC, ETH) */
+    symbol: string;
+    /** Unique market identifier */
+    marketId: number;
+    /** Market type (e.g., 'perp') */
+    marketType: string;
+    /** Market status (e.g., 'active') */
+    status: string;
+    /** Taker fee rate (e.g., 0.0005 = 0.05%) */
+    takerFee: number;
+    /** Maker fee rate (e.g., 0.0002 = 0.02%) */
+    makerFee: number;
+    /** Liquidation fee rate */
+    liquidationFee: number;
+    /** Minimum order size in base currency */
+    minBaseAmount: number;
+    /** Minimum order size in quote currency */
+    minQuoteAmount: number;
+    /** Size decimal precision */
+    sizeDecimals: number;
+    /** Price decimal precision */
+    priceDecimals: number;
+    /** Quote currency decimal precision */
+    quoteDecimals: number;
+    /** Whether the instrument is currently tradeable */
+    isActive: boolean;
+}
 /**
  * Funding rate record
  */
@@ -628,6 +662,40 @@ declare class InstrumentsResource {
      */
     get(coin: string): Promise<Instrument>;
 }
+/**
+ * Lighter.xyz Instruments API resource
+ *
+ * Lighter instruments have a different schema than Hyperliquid with more
+ * detailed market configuration including fees and minimum amounts.
+ *
+ * @example
+ * ```typescript
+ * // List all Lighter instruments
+ * const instruments = await client.lighter.instruments.list();
+ *
+ * // Get specific instrument
+ * const btc = await client.lighter.instruments.get('BTC');
+ * console.log(`Taker fee: ${btc.takerFee}`);
+ * ```
+ */
+declare class LighterInstrumentsResource {
+    private http;
+    private basePath;
+    constructor(http: HttpClient, basePath?: string);
+    /**
+     * List all available Lighter trading instruments
+     *
+     * @returns Array of Lighter instruments with full market configuration
+     */
+    list(): Promise<LighterInstrument[]>;
+    /**
+     * Get a specific Lighter instrument by coin symbol
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @returns Lighter instrument details with full market configuration
+     */
+    get(coin: string): Promise<LighterInstrument>;
+}
 
 /**
  * Funding rates API resource
@@ -766,18 +834,19 @@ declare class HyperliquidClient {
  * Lighter.xyz exchange client
  *
  * Access Lighter.xyz market data through the 0xarchive API.
- * Lighter orderbooks are reconstructed from checkpoint + delta data.
  *
  * @example
  * ```typescript
  * const client = new OxArchive({ apiKey: '...' });
  * const orderbook = await client.lighter.orderbook.get('BTC');
  * const trades = await client.lighter.trades.list('ETH', { start, end });
+ * const instruments = await client.lighter.instruments.list();
+ * console.log(`ETH taker fee: ${instruments[0].takerFee}`);
  * ```
  */
 declare class LighterClient {
     /**
-     * Order book data (reconstructed from checkpoints + deltas)
+     * Order book data (L2 snapshots)
      */
     readonly orderbook: OrderBookResource;
     /**
@@ -785,9 +854,9 @@ declare class LighterClient {
      */
     readonly trades: TradesResource;
     /**
-     * Trading instruments metadata
+     * Trading instruments metadata (returns LighterInstrument with fees, min amounts, etc.)
      */
-    readonly instruments: InstrumentsResource;
+    readonly instruments: LighterInstrumentsResource;
     /**
      * Funding rates
      */
@@ -843,7 +912,7 @@ declare class OxArchive {
      */
     readonly hyperliquid: HyperliquidClient;
     /**
-     * Lighter.xyz exchange data (orderbook reconstructed from checkpoints + deltas)
+     * Lighter.xyz exchange data (August 2025+)
      */
     readonly lighter: LighterClient;
     /**
@@ -2684,4 +2753,4 @@ type ValidatedFundingRate = z.infer<typeof FundingRateSchema>;
 type ValidatedOpenInterest = z.infer<typeof OpenInterestSchema>;
 type ValidatedWsServerMessage = z.infer<typeof WsServerMessageSchema>;
 
-export { type ApiError, type ApiMeta, ApiMetaSchema, type ApiResponse, ApiResponseSchema, type ClientOptions, type CursorResponse, type FundingRate, FundingRateArrayResponseSchema, FundingRateResponseSchema, FundingRateSchema, type GetOrderBookParams, type GetTradesCursorParams, HyperliquidClient, type Instrument, InstrumentArrayResponseSchema, InstrumentResponseSchema, InstrumentSchema, type InstrumentType, InstrumentTypeSchema, LighterClient, type OpenInterest, OpenInterestArrayResponseSchema, OpenInterestResponseSchema, OpenInterestSchema, type OrderBook, OrderBookArrayResponseSchema, type OrderBookHistoryParams, OrderBookResponseSchema, OrderBookSchema, OxArchive, OxArchiveError, OxArchiveWs, type PriceLevel, PriceLevelSchema, type Timestamp, type TimestampedRecord, TimestampedRecordSchema, type Trade, TradeArrayResponseSchema, type TradeDirection, TradeDirectionSchema, TradeSchema, type TradeSide, TradeSideSchema, type ValidatedApiMeta, type ValidatedFundingRate, type ValidatedInstrument, type ValidatedOpenInterest, type ValidatedOrderBook, type ValidatedPriceLevel, type ValidatedTrade, type ValidatedWsServerMessage, type WsChannel, WsChannelSchema, type WsClientMessage, type WsConnectionState, WsConnectionStateSchema, type WsData, WsDataSchema, type WsError, WsErrorSchema, type WsEventHandlers, type WsHistoricalBatch, WsHistoricalBatchSchema, type WsHistoricalData, WsHistoricalDataSchema, type WsOptions, type WsPing, type WsPong, WsPongSchema, type WsReplay, type WsReplayCompleted, WsReplayCompletedSchema, type WsReplayPause, type WsReplayPaused, WsReplayPausedSchema, type WsReplayResume, type WsReplayResumed, WsReplayResumedSchema, type WsReplaySeek, type WsReplayStarted, WsReplayStartedSchema, type WsReplayStop, type WsReplayStopped, WsReplayStoppedSchema, type WsServerMessage, WsServerMessageSchema, type WsStream, type WsStreamCompleted, WsStreamCompletedSchema, type WsStreamProgress, WsStreamProgressSchema, type WsStreamStarted, WsStreamStartedSchema, type WsStreamStop, type WsStreamStopped, WsStreamStoppedSchema, type WsSubscribe, type WsSubscribed, WsSubscribedSchema, type WsUnsubscribe, type WsUnsubscribed, WsUnsubscribedSchema, OxArchive as default };
+export { type ApiError, type ApiMeta, ApiMetaSchema, type ApiResponse, ApiResponseSchema, type ClientOptions, type CursorResponse, type FundingRate, FundingRateArrayResponseSchema, FundingRateResponseSchema, FundingRateSchema, type GetOrderBookParams, type GetTradesCursorParams, HyperliquidClient, type Instrument, InstrumentArrayResponseSchema, InstrumentResponseSchema, InstrumentSchema, type InstrumentType, InstrumentTypeSchema, LighterClient, type LighterInstrument, type OpenInterest, OpenInterestArrayResponseSchema, OpenInterestResponseSchema, OpenInterestSchema, type OrderBook, OrderBookArrayResponseSchema, type OrderBookHistoryParams, OrderBookResponseSchema, OrderBookSchema, OxArchive, OxArchiveError, OxArchiveWs, type PriceLevel, PriceLevelSchema, type Timestamp, type TimestampedRecord, TimestampedRecordSchema, type Trade, TradeArrayResponseSchema, type TradeDirection, TradeDirectionSchema, TradeSchema, type TradeSide, TradeSideSchema, type ValidatedApiMeta, type ValidatedFundingRate, type ValidatedInstrument, type ValidatedOpenInterest, type ValidatedOrderBook, type ValidatedPriceLevel, type ValidatedTrade, type ValidatedWsServerMessage, type WsChannel, WsChannelSchema, type WsClientMessage, type WsConnectionState, WsConnectionStateSchema, type WsData, WsDataSchema, type WsError, WsErrorSchema, type WsEventHandlers, type WsHistoricalBatch, WsHistoricalBatchSchema, type WsHistoricalData, WsHistoricalDataSchema, type WsOptions, type WsPing, type WsPong, WsPongSchema, type WsReplay, type WsReplayCompleted, WsReplayCompletedSchema, type WsReplayPause, type WsReplayPaused, WsReplayPausedSchema, type WsReplayResume, type WsReplayResumed, WsReplayResumedSchema, type WsReplaySeek, type WsReplayStarted, WsReplayStartedSchema, type WsReplayStop, type WsReplayStopped, WsReplayStoppedSchema, type WsServerMessage, WsServerMessageSchema, type WsStream, type WsStreamCompleted, WsStreamCompletedSchema, type WsStreamProgress, WsStreamProgressSchema, type WsStreamStarted, WsStreamStartedSchema, type WsStreamStop, type WsStreamStopped, WsStreamStoppedSchema, type WsSubscribe, type WsSubscribed, WsSubscribedSchema, type WsUnsubscribe, type WsUnsubscribed, WsUnsubscribedSchema, OxArchive as default };

package/dist/index.d.ts

@@ -148,7 +148,7 @@ interface CursorResponse<T> {
 /** Instrument type */
 type InstrumentType = 'perp' | 'spot';
 /**
- * Trading instrument metadata
+ * Trading instrument metadata (Hyperliquid)
  */
 interface Instrument {
     /** Instrument symbol (e.g., BTC) */
@@ -164,6 +164,40 @@ interface Instrument {
     /** Whether the instrument is currently tradeable */
     isActive: boolean;
 }
+/**
+ * Trading instrument metadata (Lighter.xyz)
+ *
+ * Lighter instruments have a different schema than Hyperliquid with more
+ * detailed market configuration including fees and minimum amounts.
+ */
+interface LighterInstrument {
+    /** Instrument symbol (e.g., BTC, ETH) */
+    symbol: string;
+    /** Unique market identifier */
+    marketId: number;
+    /** Market type (e.g., 'perp') */
+    marketType: string;
+    /** Market status (e.g., 'active') */
+    status: string;
+    /** Taker fee rate (e.g., 0.0005 = 0.05%) */
+    takerFee: number;
+    /** Maker fee rate (e.g., 0.0002 = 0.02%) */
+    makerFee: number;
+    /** Liquidation fee rate */
+    liquidationFee: number;
+    /** Minimum order size in base currency */
+    minBaseAmount: number;
+    /** Minimum order size in quote currency */
+    minQuoteAmount: number;
+    /** Size decimal precision */
+    sizeDecimals: number;
+    /** Price decimal precision */
+    priceDecimals: number;
+    /** Quote currency decimal precision */
+    quoteDecimals: number;
+    /** Whether the instrument is currently tradeable */
+    isActive: boolean;
+}
 /**
  * Funding rate record
  */
@@ -628,6 +662,40 @@ declare class InstrumentsResource {
      */
     get(coin: string): Promise<Instrument>;
 }
+/**
+ * Lighter.xyz Instruments API resource
+ *
+ * Lighter instruments have a different schema than Hyperliquid with more
+ * detailed market configuration including fees and minimum amounts.
+ *
+ * @example
+ * ```typescript
+ * // List all Lighter instruments
+ * const instruments = await client.lighter.instruments.list();
+ *
+ * // Get specific instrument
+ * const btc = await client.lighter.instruments.get('BTC');
+ * console.log(`Taker fee: ${btc.takerFee}`);
+ * ```
+ */
+declare class LighterInstrumentsResource {
+    private http;
+    private basePath;
+    constructor(http: HttpClient, basePath?: string);
+    /**
+     * List all available Lighter trading instruments
+     *
+     * @returns Array of Lighter instruments with full market configuration
+     */
+    list(): Promise<LighterInstrument[]>;
+    /**
+     * Get a specific Lighter instrument by coin symbol
+     *
+     * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+     * @returns Lighter instrument details with full market configuration
+     */
+    get(coin: string): Promise<LighterInstrument>;
+}
 
 /**
  * Funding rates API resource
@@ -766,18 +834,19 @@ declare class HyperliquidClient {
  * Lighter.xyz exchange client
  *
  * Access Lighter.xyz market data through the 0xarchive API.
- * Lighter orderbooks are reconstructed from checkpoint + delta data.
  *
  * @example
  * ```typescript
  * const client = new OxArchive({ apiKey: '...' });
  * const orderbook = await client.lighter.orderbook.get('BTC');
  * const trades = await client.lighter.trades.list('ETH', { start, end });
+ * const instruments = await client.lighter.instruments.list();
+ * console.log(`ETH taker fee: ${instruments[0].takerFee}`);
  * ```
  */
 declare class LighterClient {
     /**
-     * Order book data (reconstructed from checkpoints + deltas)
+     * Order book data (L2 snapshots)
      */
     readonly orderbook: OrderBookResource;
     /**
@@ -785,9 +854,9 @@ declare class LighterClient {
      */
     readonly trades: TradesResource;
     /**
-     * Trading instruments metadata
+     * Trading instruments metadata (returns LighterInstrument with fees, min amounts, etc.)
      */
-    readonly instruments: InstrumentsResource;
+    readonly instruments: LighterInstrumentsResource;
     /**
      * Funding rates
      */
@@ -843,7 +912,7 @@ declare class OxArchive {
      */
     readonly hyperliquid: HyperliquidClient;
     /**
-     * Lighter.xyz exchange data (orderbook reconstructed from checkpoints + deltas)
+     * Lighter.xyz exchange data (August 2025+)
      */
     readonly lighter: LighterClient;
     /**
@@ -2684,4 +2753,4 @@ type ValidatedFundingRate = z.infer<typeof FundingRateSchema>;
 type ValidatedOpenInterest = z.infer<typeof OpenInterestSchema>;
 type ValidatedWsServerMessage = z.infer<typeof WsServerMessageSchema>;
 
-export { type ApiError, type ApiMeta, ApiMetaSchema, type ApiResponse, ApiResponseSchema, type ClientOptions, type CursorResponse, type FundingRate, FundingRateArrayResponseSchema, FundingRateResponseSchema, FundingRateSchema, type GetOrderBookParams, type GetTradesCursorParams, HyperliquidClient, type Instrument, InstrumentArrayResponseSchema, InstrumentResponseSchema, InstrumentSchema, type InstrumentType, InstrumentTypeSchema, LighterClient, type OpenInterest, OpenInterestArrayResponseSchema, OpenInterestResponseSchema, OpenInterestSchema, type OrderBook, OrderBookArrayResponseSchema, type OrderBookHistoryParams, OrderBookResponseSchema, OrderBookSchema, OxArchive, OxArchiveError, OxArchiveWs, type PriceLevel, PriceLevelSchema, type Timestamp, type TimestampedRecord, TimestampedRecordSchema, type Trade, TradeArrayResponseSchema, type TradeDirection, TradeDirectionSchema, TradeSchema, type TradeSide, TradeSideSchema, type ValidatedApiMeta, type ValidatedFundingRate, type ValidatedInstrument, type ValidatedOpenInterest, type ValidatedOrderBook, type ValidatedPriceLevel, type ValidatedTrade, type ValidatedWsServerMessage, type WsChannel, WsChannelSchema, type WsClientMessage, type WsConnectionState, WsConnectionStateSchema, type WsData, WsDataSchema, type WsError, WsErrorSchema, type WsEventHandlers, type WsHistoricalBatch, WsHistoricalBatchSchema, type WsHistoricalData, WsHistoricalDataSchema, type WsOptions, type WsPing, type WsPong, WsPongSchema, type WsReplay, type WsReplayCompleted, WsReplayCompletedSchema, type WsReplayPause, type WsReplayPaused, WsReplayPausedSchema, type WsReplayResume, type WsReplayResumed, WsReplayResumedSchema, type WsReplaySeek, type WsReplayStarted, WsReplayStartedSchema, type WsReplayStop, type WsReplayStopped, WsReplayStoppedSchema, type WsServerMessage, WsServerMessageSchema, type WsStream, type WsStreamCompleted, WsStreamCompletedSchema, type WsStreamProgress, WsStreamProgressSchema, type WsStreamStarted, WsStreamStartedSchema, type WsStreamStop, type WsStreamStopped, WsStreamStoppedSchema, type WsSubscribe, type WsSubscribed, WsSubscribedSchema, type WsUnsubscribe, type WsUnsubscribed, WsUnsubscribedSchema, OxArchive as default };
+export { type ApiError, type ApiMeta, ApiMetaSchema, type ApiResponse, ApiResponseSchema, type ClientOptions, type CursorResponse, type FundingRate, FundingRateArrayResponseSchema, FundingRateResponseSchema, FundingRateSchema, type GetOrderBookParams, type GetTradesCursorParams, HyperliquidClient, type Instrument, InstrumentArrayResponseSchema, InstrumentResponseSchema, InstrumentSchema, type InstrumentType, InstrumentTypeSchema, LighterClient, type LighterInstrument, type OpenInterest, OpenInterestArrayResponseSchema, OpenInterestResponseSchema, OpenInterestSchema, type OrderBook, OrderBookArrayResponseSchema, type OrderBookHistoryParams, OrderBookResponseSchema, OrderBookSchema, OxArchive, OxArchiveError, OxArchiveWs, type PriceLevel, PriceLevelSchema, type Timestamp, type TimestampedRecord, TimestampedRecordSchema, type Trade, TradeArrayResponseSchema, type TradeDirection, TradeDirectionSchema, TradeSchema, type TradeSide, TradeSideSchema, type ValidatedApiMeta, type ValidatedFundingRate, type ValidatedInstrument, type ValidatedOpenInterest, type ValidatedOrderBook, type ValidatedPriceLevel, type ValidatedTrade, type ValidatedWsServerMessage, type WsChannel, WsChannelSchema, type WsClientMessage, type WsConnectionState, WsConnectionStateSchema, type WsData, WsDataSchema, type WsError, WsErrorSchema, type WsEventHandlers, type WsHistoricalBatch, WsHistoricalBatchSchema, type WsHistoricalData, WsHistoricalDataSchema, type WsOptions, type WsPing, type WsPong, WsPongSchema, type WsReplay, type WsReplayCompleted, WsReplayCompletedSchema, type WsReplayPause, type WsReplayPaused, WsReplayPausedSchema, type WsReplayResume, type WsReplayResumed, WsReplayResumedSchema, type WsReplaySeek, type WsReplayStarted, WsReplayStartedSchema, type WsReplayStop, type WsReplayStopped, WsReplayStoppedSchema, type WsServerMessage, WsServerMessageSchema, type WsStream, type WsStreamCompleted, WsStreamCompletedSchema, type WsStreamProgress, WsStreamProgressSchema, type WsStreamStarted, WsStreamStartedSchema, type WsStreamStop, type WsStreamStopped, WsStreamStoppedSchema, type WsSubscribe, type WsSubscribed, WsSubscribedSchema, type WsUnsubscribe, type WsUnsubscribed, WsUnsubscribedSchema, OxArchive as default };

package/dist/index.js

@@ -537,6 +537,35 @@ var InstrumentsResource = class {
     return response.data;
   }
 };
+var LighterInstrumentsResource = class {
+  constructor(http, basePath = "/v1/lighter") {
+    this.http = http;
+    this.basePath = basePath;
+  }
+  /**
+   * List all available Lighter trading instruments
+   *
+   * @returns Array of Lighter instruments with full market configuration
+   */
+  async list() {
+    const response = await this.http.get(
+      `${this.basePath}/instruments`
+    );
+    return response.data;
+  }
+  /**
+   * Get a specific Lighter instrument by coin symbol
+   *
+   * @param coin - The coin symbol (e.g., 'BTC', 'ETH')
+   * @returns Lighter instrument details with full market configuration
+   */
+  async get(coin) {
+    const response = await this.http.get(
+      `${this.basePath}/instruments/${coin.toUpperCase()}`
+    );
+    return response.data;
+  }
+};
 
 // src/resources/funding.ts
 var FundingResource = class {
@@ -651,7 +680,7 @@ var HyperliquidClient = class {
 };
 var LighterClient = class {
   /**
-   * Order book data (reconstructed from checkpoints + deltas)
+   * Order book data (L2 snapshots)
    */
   orderbook;
   /**
@@ -659,7 +688,7 @@ var LighterClient = class {
    */
   trades;
   /**
-   * Trading instruments metadata
+   * Trading instruments metadata (returns LighterInstrument with fees, min amounts, etc.)
    */
   instruments;
   /**
@@ -674,7 +703,7 @@ var LighterClient = class {
     const basePath = "/v1/lighter";
     this.orderbook = new OrderBookResource(http, basePath);
     this.trades = new TradesResource(http, basePath);
-    this.instruments = new InstrumentsResource(http, basePath);
+    this.instruments = new LighterInstrumentsResource(http, basePath);
     this.funding = new FundingResource(http, basePath);
     this.openInterest = new OpenInterestResource(http, basePath);
   }
@@ -690,7 +719,7 @@ var OxArchive = class {
    */
   hyperliquid;
   /**
-   * Lighter.xyz exchange data (orderbook reconstructed from checkpoints + deltas)
+   * Lighter.xyz exchange data (August 2025+)
    */
   lighter;
   /**