@gearbox-protocol/sdk 14.12.0-next.71 → 14.12.0-next.72

package/dist/esm/model/history.js

@@ -22,5 +22,28 @@ const STRATEGY_HISTORY_METRICS = [
 	"collateralUsdPrice",
 	"underlyingUsdPrice"
 ];
+/**
+* Every {@link PoolPositionHistoryMetric}, for callers that enumerate them.
+**/
+const POOL_POSITION_HISTORY_METRICS = [
+	"depositApy",
+	"borrowApy",
+	"dieselRate",
+	"supplied",
+	"borrowed",
+	"availableLiquidity"
+];
+/**
+* Every {@link StrategyPositionHistoryMetric}, for callers that enumerate them.
+**/
+const STRATEGY_POSITION_HISTORY_METRICS = [
+	"netApy",
+	"borrowApy",
+	"collateralApy",
+	"tvl",
+	"collateralPrice",
+	"collateralUsdPrice",
+	"underlyingUsdPrice"
+];
 //#endregion
-export { POOL_HISTORY_METRICS, STRATEGY_HISTORY_METRICS };
+export { POOL_HISTORY_METRICS, POOL_POSITION_HISTORY_METRICS, STRATEGY_HISTORY_METRICS, STRATEGY_POSITION_HISTORY_METRICS };

package/dist/esm/model/history.schema.js

@@ -1,5 +1,6 @@
 import { timestampSchema } from "./primitives.schema.js";
 import { opportunityKeySchema } from "./opportunities.schema.js";
+import { positionKeySchema } from "./positions.schema.js";
 import { z } from "zod/v4";
 //#region src/model/history.schema.ts
 /**
@@ -40,9 +41,40 @@ const strategyHistoryMetricSchema = z.union([
 	z.literal("underlyingUsdPrice")
 ]);
 /**
+* {@link PoolPositionHistoryMetric}
+**/
+const poolPositionHistoryMetricSchema = z.union([
+	z.literal("depositApy"),
+	z.literal("borrowApy"),
+	z.literal("dieselRate"),
+	z.literal("supplied"),
+	z.literal("borrowed"),
+	z.literal("availableLiquidity")
+]);
+/**
+* {@link StrategyPositionHistoryMetric}
+**/
+const strategyPositionHistoryMetricSchema = z.union([
+	z.literal("netApy"),
+	z.literal("borrowApy"),
+	z.literal("collateralApy"),
+	z.literal("tvl"),
+	z.literal("collateralPrice"),
+	z.literal("collateralUsdPrice"),
+	z.literal("underlyingUsdPrice")
+]);
+/**
+* {@link PositionHistoryMetric}
+**/
+const positionHistoryMetricSchema = z.union([poolPositionHistoryMetricSchema, strategyPositionHistoryMetricSchema]);
+/**
 * {@link HistoryMetric}
 **/
-const historyMetricSchema = z.union([poolHistoryMetricSchema, strategyHistoryMetricSchema]);
+const historyMetricSchema = z.union([
+	poolHistoryMetricSchema,
+	strategyHistoryMetricSchema,
+	positionHistoryMetricSchema
+]);
 /**
 * {@link HistoryPoint}
 **/
@@ -72,5 +104,13 @@ const opportunityHistoryQuerySchema = z.object({
 	range: historyRangeSchema,
 	metric: historyMetricSchema
 });
+/**
+* {@link PositionHistoryQuery}
+**/
+const positionHistoryQuerySchema = z.object({
+	position: positionKeySchema,
+	range: historyRangeSchema,
+	metric: positionHistoryMetricSchema
+});
 //#endregion
-export { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, strategyHistoryMetricSchema };
+export { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, poolPositionHistoryMetricSchema, positionHistoryMetricSchema, positionHistoryQuerySchema, strategyHistoryMetricSchema, strategyPositionHistoryMetricSchema };

package/dist/esm/model/index.js

@@ -1,11 +1,11 @@
-import { POOL_HISTORY_METRICS, STRATEGY_HISTORY_METRICS } from "./history.js";
+import { POOL_HISTORY_METRICS, POOL_POSITION_HISTORY_METRICS, STRATEGY_HISTORY_METRICS, STRATEGY_POSITION_HISTORY_METRICS } from "./history.js";
 import { amountSchema, assetTypeSchema, bpsSchema, chainIdSchema, curatorSchema, leverageSchema, timestampSchema, tokenAmountSchema, tokenSchema, txCallSchema } from "./primitives.schema.js";
 import { apyBreakdownSchema, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterSchema, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pointRewardsSchema, pointsProgramSchema, poolOpportunityDetailSchema, poolOpportunityKeySchema, poolOpportunitySchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, rewardsSchema, strategyOpportunityDetailSchema, strategyOpportunityKeySchema, strategyOpportunitySchema, tokenRewardsSchema } from "./opportunities.schema.js";
-import { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, strategyHistoryMetricSchema } from "./history.schema.js";
-import { matchesLiquidatableAccountFilter } from "./liquidations.js";
 import { delayedReceivedAssetSchema, instantReceivedAssetSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionSchema, receivedAssetSchema } from "./liquidations.schema.js";
+import { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema } from "./positions.schema.js";
+import { historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, opportunityHistoryQuerySchema, poolHistoryMetricSchema, poolPositionHistoryMetricSchema, positionHistoryMetricSchema, positionHistoryQuerySchema, strategyHistoryMetricSchema, strategyPositionHistoryMetricSchema } from "./history.schema.js";
+import { matchesLiquidatableAccountFilter } from "./liquidations.js";
 import { matchesOpportunityFilter, opportunityId, poolOpportunityId, strategyOpportunityId } from "./opportunities.js";
-import "./positions.js";
-import { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionSchema, tokenRewardsPnLSchema } from "./positions.schema.js";
+import { liquidationPositionId, matchesPositionFilter, poolPositionId, positionId, strategyPositionId } from "./positions.js";
 import "./primitives.js";
-export { POOL_HISTORY_METRICS, STRATEGY_HISTORY_METRICS, amountSchema, apyBreakdownSchema, assetTypeSchema, bpsSchema, chainIdSchema, curatorSchema, delayedReceivedAssetSchema, historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, instantReceivedAssetSchema, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterSchema, opportunityHistoryQuerySchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pnlBreakdownSchema, pointRewardsSchema, pointsProgramPnLSchema, pointsProgramSchema, pointsRewardsPnLSchema, poolHistoryMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionKindSchema, positionSchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, rewardsPnLSchema, rewardsSchema, strategyHistoryMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, strategyPositionSchema, timestampSchema, tokenAmountSchema, tokenRewardsPnLSchema, tokenRewardsSchema, tokenSchema, txCallSchema };
+export { POOL_HISTORY_METRICS, POOL_POSITION_HISTORY_METRICS, STRATEGY_HISTORY_METRICS, STRATEGY_POSITION_HISTORY_METRICS, amountSchema, apyBreakdownSchema, assetTypeSchema, bpsSchema, chainIdSchema, curatorSchema, delayedReceivedAssetSchema, historyChartMetadataSchema, historyMetricSchema, historyPointSchema, historyRangeSchema, historySeriesSchema, instantReceivedAssetSchema, leverageSchema, liquidatableAccountFilterSchema, liquidatableAccountSchema, liquidationApprovalSchema, liquidationDetailsSchema, liquidationPositionId, liquidationPositionSchema, matchesLiquidatableAccountFilter, matchesOpportunityFilter, matchesPositionFilter, opportunityBaseSchema, opportunityDetailSchema, opportunityFilterSchema, opportunityHistoryQuerySchema, opportunityId, opportunityKeySchema, opportunityKindSchema, opportunitySchema, pnlBreakdownSchema, pointRewardsSchema, pointsProgramPnLSchema, pointsProgramSchema, pointsRewardsPnLSchema, poolHistoryMetricSchema, poolOpportunityDetailSchema, poolOpportunityId, poolOpportunityKeySchema, poolOpportunitySchema, poolPositionHistoryMetricSchema, poolPositionId, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionHistoryMetricSchema, positionHistoryQuerySchema, positionId, positionKeySchema, positionKindSchema, positionSchema, priceFeedDataSchema, priceFeedSummarySchema, quotaAssetSchema, rateCurvePointSchema, rateCurveSchema, receivedAssetSchema, rewardsPnLSchema, rewardsSchema, strategyHistoryMetricSchema, strategyOpportunityDetailSchema, strategyOpportunityId, strategyOpportunityKeySchema, strategyOpportunitySchema, strategyPositionHistoryMetricSchema, strategyPositionId, strategyPositionKeySchema, strategyPositionSchema, timestampSchema, tokenAmountSchema, tokenRewardsPnLSchema, tokenRewardsSchema, tokenSchema, txCallSchema };

package/dist/esm/model/positions.js

@@ -1 +1,85 @@
-export {};
+//#region src/model/positions.ts
+/**
+* Builds the canonical id of a pool position.
+*
+* @example
+* ```ts
+* poolPositionId(1, "0xda00...") // "1:pool:0xda00..."
+* ```
+**/
+function poolPositionId(chainId, pool) {
+	return `${chainId}:pool:${pool.toLowerCase()}`;
+}
+/**
+* Builds the canonical id of a strategy position. The credit account address
+* identifies it on its own, the credit manager is not part of the id.
+*
+* @example
+* ```ts
+* strategyPositionId(1, "0x9c4c...") // "1:strategy:0x9c4c..."
+* ```
+**/
+function strategyPositionId(chainId, creditAccount) {
+	return `${chainId}:strategy:${creditAccount.toLowerCase()}`;
+}
+/**
+* Builds the canonical id of a liquidation position.
+*
+* The redeemer is the withdrawal's own contract and therefore identifies it,
+* but compressor versions below 313 do not report one; those fall back to the
+* source token plus the moment the withdrawal becomes claimable, which is what
+* distinguishes two withdrawals of the same asset.
+**/
+function liquidationPositionId(chainId, position) {
+	const { redeemer, sourceToken, claimableAt } = position;
+	return `${chainId}:liquidation:${redeemer ? redeemer.toLowerCase() : `${sourceToken.address.toLowerCase()}:${claimableAt ?? "claimable"}`}`;
+}
+/**
+* Canonical id of any position, dispatching on {@link Position.kind}.
+**/
+function positionId(position) {
+	switch (position.kind) {
+		case "pool": return poolPositionId(position.chainId, position.pool);
+		case "strategy": return strategyPositionId(position.chainId, position.creditAccount);
+		case "liquidation": return liquidationPositionId(position.chainId, position);
+	}
+}
+/**
+* Whether a position satisfies every criterion of a filter.
+*
+* This is the single definition of what each criterion means: every source
+* builds its rows first and runs them through here, so the chain and the
+* backend cannot disagree on what a filter selects.
+*
+* A criterion that does not apply to a position's kind keeps the row rather
+* than dropping it: `isZeroDebt` says nothing about a pool position, and
+* `underlyingType` says nothing about a liquidation position, which is
+* denominated in whatever its withdrawal pays out.
+*
+* @param position - Row to test.
+* @param filter - Criteria to test against. An absent filter matches anything.
+**/
+function matchesPositionFilter(position, filter) {
+	if (!filter) return true;
+	if (filter.kind && position.kind !== filter.kind) return false;
+	if (filter.chainIds && !filter.chainIds.includes(position.chainId)) return false;
+	if (filter.isZeroDebt !== void 0 && position.kind === "strategy" && position.totalDebt.value === 0n !== filter.isZeroDebt) return false;
+	if (filter.underlyingType) {
+		const underlying = positionUnderlying(position);
+		if (underlying && underlying.assetType !== filter.underlyingType) return false;
+	}
+	return true;
+}
+/**
+* Token a position's headline amount is denominated in, or `undefined` for a
+* kind that has no single underlying.
+**/
+function positionUnderlying(position) {
+	switch (position.kind) {
+		case "pool": return position.netValue.token;
+		case "strategy": return position.totalValue.token;
+		case "liquidation": return;
+	}
+}
+//#endregion
+export { liquidationPositionId, matchesPositionFilter, poolPositionId, positionId, strategyPositionId };

package/dist/esm/model/positions.schema.js

@@ -105,5 +105,30 @@ const positionFilterSchema = z.object({
 	chainIds: z.array(chainIdSchema).optional(),
 	underlyingType: assetTypeSchema.optional()
 });
+/**
+* {@link PoolPositionKey}
+**/
+const poolPositionKeySchema = z.object({
+	chainId: chainIdSchema,
+	pool: ZodAddress(),
+	wallet: ZodAddress()
+});
+/**
+* {@link StrategyPositionKey}
+**/
+const strategyPositionKeySchema = z.object({
+	chainId: chainIdSchema,
+	creditAccount: ZodAddress()
+});
+/**
+* {@link PositionKey}
+**/
+const positionKeySchema = z.discriminatedUnion("kind", [z.object({
+	kind: z.literal("pool"),
+	...poolPositionKeySchema.shape
+}), z.object({
+	kind: z.literal("strategy"),
+	...strategyPositionKeySchema.shape
+})]);
 //#endregion
-export { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionSchema, tokenRewardsPnLSchema };
+export { pnlBreakdownSchema, pointsProgramPnLSchema, pointsRewardsPnLSchema, poolPositionKeySchema, poolPositionSchema, positionCollateralSchema, positionFilterSchema, positionKeySchema, positionKindSchema, positionSchema, rewardsPnLSchema, strategyPositionKeySchema, strategyPositionSchema, tokenRewardsPnLSchema };

package/dist/esm/new-sdk/GearboxSDK.js

@@ -4,6 +4,8 @@ import { GearboxAPI } from "../offchain/GearboxAPI.js";
 import "../offchain/index.js";
 import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.js";
 import "./opportunities/index.js";
+import { PositionsNamespace } from "./positions/PositionsNamespace.js";
+import "./positions/index.js";
 //#region src/new-sdk/GearboxSDK.ts
 /**
 * Combined entry point over both sources of Gearbox data: the chain and the
@@ -45,6 +47,10 @@ var GearboxSDK = class {
 	* Namespace for pool and strategy opportunities.
 	**/
 	opportunities;
+	/**
+	* Namespace for the positions a wallet holds.
+	**/
+	positions;
 	#attachOptions;
 	#onchain;
 	#offchain;
@@ -78,6 +84,7 @@ var GearboxSDK = class {
 		});
 		this.#attached = !this.#ownsOnchain;
 		this.opportunities = new OpportunitiesNamespace(this.#onchain, this.#offchain, logger);
+		this.positions = new PositionsNamespace(this.#onchain, this.#offchain, logger);
 	}
 	/**
 	* Attaches the on-chain SDK when this instance owns one.

package/dist/esm/new-sdk/index.js

@@ -2,6 +2,8 @@ import { AllSourcesFailedError } from "./types.js";
 import { AbstractNamespace } from "./AbstractNamespace.js";
 import { OpportunitiesNamespace } from "./opportunities/OpportunitiesNamespace.js";
 import "./opportunities/index.js";
+import { PositionsNamespace } from "./positions/PositionsNamespace.js";
+import "./positions/index.js";
 import { GearboxSDK } from "./GearboxSDK.js";
 import "./utils/index.js";
-export { AbstractNamespace, AllSourcesFailedError, GearboxSDK, OpportunitiesNamespace };
+export { AbstractNamespace, AllSourcesFailedError, GearboxSDK, OpportunitiesNamespace, PositionsNamespace };

package/dist/esm/new-sdk/positions/PositionsNamespace.js

@@ -0,0 +1,118 @@
+import { positionId } from "../../model/positions.js";
+import "../../model/index.js";
+import { AbstractNamespace } from "../AbstractNamespace.js";
+//#region src/new-sdk/positions/PositionsNamespace.ts
+/**
+* Fields the backend owns even when the chain also fills them.
+*
+* The yield and PnL groups are derived from a position's history and from
+* incentive programs, neither of which the chain has. `targetCollateral` is
+* there for a subtler reason: the read model defines it as the collateral the
+* position was opened into, which only the backend can know, while the chain
+* approximates it with the dominant collateral held right now.
+**/
+const OFFCHAIN_OWNED_FIELDS = /* @__PURE__ */ new Set([
+	"apy",
+	"netApy",
+	"pnl",
+	"targetCollateral"
+]);
+/**
+* The `positions` namespace of the combined SDK.
+*
+* A stateless router over the two sources, see {@link AbstractNamespace} for the
+* routing itself. What is specific to positions is the reads below and the merge
+* policy at the bottom of the class.
+*
+* The class implements the methods of every mode; {@link GearboxSDK} exposes it
+* as its mode's slice of {@link PositionsByMode}, so calling a method the mode
+* does not have is a compile error rather than a runtime one.
+**/
+var PositionsNamespace = class extends AbstractNamespace {
+	constructor(onchain, offchain, logger) {
+		super("Positions", onchain, offchain, logger);
+	}
+	/**
+	* {@inheritDoc PositionsBase.list}
+	**/
+	async list(wallet, filter) {
+		return this.readList("list positions", async (sdk) => {
+			const { result, meta } = await sdk.positions.list({
+				wallet,
+				filter
+			});
+			return {
+				value: result,
+				chains: meta
+			};
+		}, (api) => api.positions.list(wallet, filter));
+	}
+	history(key) {
+		return { chart: (metric, range) => this.#chart(key, metric, range) };
+	}
+	/**
+	* Reads one chart of one position from the backend.
+	*
+	* The metric a caller may name is gated by the reader's type, so the kind of
+	* the key is not re-checked here.
+	**/
+	async #chart(key, metric, range) {
+		const { result, meta } = await this.readOffchain(`get ${metric} history`, (api) => api.positions.getHistory({
+			position: key,
+			range,
+			metric
+		}), {
+			metric,
+			points: [],
+			metadata: {}
+		});
+		return {
+			data: result.points,
+			metadata: {
+				...result.metadata,
+				source: meta
+			}
+		};
+	}
+	/**
+	* Merges the two versions of one position.
+	*
+	* The chain wins every field it fills; the backend fills the rest and owns
+	* {@link OFFCHAIN_OWNED_FIELDS}.
+	*
+	* The rule is onchain-first, field-wise, and never deeper than one level: a
+	* group like `totalValue` or `apy` is taken whole from one source, so a row
+	* never mixes an on-chain token amount with a backend dollar value derived
+	* from a different block.
+	**/
+	mergeOne(onchain, offchain) {
+		const merged = { ...onchain };
+		for (const [field, value] of Object.entries(offchain)) {
+			if (value === void 0) continue;
+			if (OFFCHAIN_OWNED_FIELDS.has(field) || merged[field] === void 0) merged[field] = value;
+		}
+		return merged;
+	}
+	/**
+	* Unions the two lists by canonical position id.
+	*
+	* Rows present in both are merged by {@link PositionsNamespace.mergeOne}.
+	* Rows only the backend knows are appended: a chain the SDK does not cover,
+	* or a market it has not loaded, must not hide a position the wallet actually
+	* holds.
+	**/
+	mergeList(onchain, offchain) {
+		const byId = /* @__PURE__ */ new Map();
+		for (const row of onchain) byId.set(positionId(row), row);
+		const extra = [];
+		for (const row of offchain) {
+			const id = positionId(row);
+			const existing = byId.get(id);
+			if (existing) byId.set(id, this.mergeOne(existing, row));
+			else extra.push(row);
+		}
+		return [...byId.values(), ...extra];
+	}
+};
+//#endregion
+export { PositionsNamespace };

package/dist/esm/new-sdk/positions/index.js

@@ -0,0 +1,3 @@
+import { PositionsNamespace } from "./PositionsNamespace.js";
+import "./types.js";
+export { PositionsNamespace };

package/dist/esm/new-sdk/positions/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/offchain/GearboxAPI.js

@@ -1,5 +1,7 @@
 import { OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
 import "./opportunities/index.js";
+import { OffchainPositions } from "./positions/OffchainPositions.js";
+import "./positions/index.js";
 //#region src/offchain/GearboxAPI.ts
 /**
 * Client for the Gearbox backend, the off-chain source of the read model.
@@ -16,16 +18,21 @@ import "./opportunities/index.js";
 * return those types directly, so there is no wire DTO layer here — only
 * transport and schema validation.
 *
-* The transport is not implemented yet; see {@link OffchainOpportunities} for
-* what each stubbed endpoint currently answers.
+* The transport is not implemented yet; see {@link OffchainOpportunities} and
+* {@link OffchainPositions} for what each stubbed endpoint currently answers.
 **/
 var GearboxAPI = class {
 	/**
 	* Namespace for pool and strategy opportunities.
 	**/
 	opportunities;
+	/**
+	* Namespace for the positions a wallet holds.
+	**/
+	positions;
 	constructor(options) {
 		this.opportunities = new OffchainOpportunities(options);
+		this.positions = new OffchainPositions(options);
 	}
 };
 //#endregion

package/dist/esm/offchain/index.js

@@ -1,5 +1,7 @@
-import { OffchainNotImplementedError, OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
+import { OffchainNotImplementedError } from "./types.js";
+import { OffchainOpportunities } from "./opportunities/OffchainOpportunities.js";
 import "./opportunities/index.js";
+import { OffchainPositions } from "./positions/OffchainPositions.js";
+import "./positions/index.js";
 import { GearboxAPI } from "./GearboxAPI.js";
-import "./types.js";
-export { GearboxAPI, OffchainNotImplementedError, OffchainOpportunities };
+export { GearboxAPI, OffchainNotImplementedError, OffchainOpportunities, OffchainPositions };

package/dist/esm/offchain/opportunities/OffchainOpportunities.js

@@ -1,16 +1,6 @@
+import { OffchainNotImplementedError } from "../types.js";
 //#region src/offchain/opportunities/OffchainOpportunities.ts
 /**
-* Thrown by the endpoints that have no stub answer, so that a caller in
-* `offchain` mode fails loudly instead of reading an empty detail page as a
-* missing opportunity.
-**/
-var OffchainNotImplementedError = class extends Error {
-	constructor(endpoint) {
-		super(`GearboxAPI: ${endpoint} is not implemented yet`);
-		this.name = "OffchainNotImplementedError";
-	}
-};
-/**
 * Backend counterpart of the `opportunities` namespace.
 *
 * This is a stub: the HTTP client is not written yet, so list reads answer with
@@ -92,4 +82,4 @@ var OffchainOpportunities = class {
 	}
 };
 //#endregion
-export { OffchainNotImplementedError, OffchainOpportunities };
+export { OffchainOpportunities };

package/dist/esm/offchain/opportunities/index.js

@@ -1,2 +1,2 @@
-import { OffchainNotImplementedError, OffchainOpportunities } from "./OffchainOpportunities.js";
-export { OffchainNotImplementedError, OffchainOpportunities };
+import { OffchainOpportunities } from "./OffchainOpportunities.js";
+export { OffchainOpportunities };

package/dist/esm/offchain/positions/OffchainPositions.js

@@ -0,0 +1,68 @@
+//#region src/offchain/positions/OffchainPositions.ts
+/**
+* Backend counterpart of the `positions` namespace.
+*
+* This is a stub: the HTTP client is not written yet, so reads answer with an
+* empty payload. Every signature is already the final one, because the backend
+* returns the read model types directly — there is no wire DTO and no mapper
+* between the two.
+*
+* When the transport lands, each method will validate the response against the
+* matching schema from `src/model` before returning it. A validation failure is
+* a version-skew error and is handled exactly like a transport error: the
+* combined SDK drops the backend's contribution in `both` mode and rethrows in
+* `offchain` mode.
+**/
+var OffchainPositions = class {
+	#baseUrl;
+	#logger;
+	constructor(options) {
+		this.#baseUrl = options?.baseUrl;
+		this.#logger = options?.logger?.child?.({ name: "OffchainPositions" });
+	}
+	/**
+	* Base URL the client will call once the transport is implemented.
+	**/
+	get baseUrl() {
+		return this.#baseUrl;
+	}
+	/**
+	* Everything a wallet holds, optionally narrowed by {@link PositionFilter}.
+	*
+	* @returns An empty list until the backend client is implemented.
+	**/
+	async list(wallet, filter) {
+		this.#logger?.debug({
+			wallet,
+			filter
+		}, "offchain positions list is not implemented, serving empty list");
+		return {
+			result: [],
+			meta: { status: "success" }
+		};
+	}
+	/**
+	* One historical series of one position. History exists only here: rebuilding
+	* it from the chain would mean an archive read per point.
+	*
+	* The requested metric types the response, so a caller asking for one metric
+	* does not have to narrow the union back down. When the transport lands,
+	* validation is what upholds it: a response carrying a different metric than
+	* the one asked for is a version-skew error like any other.
+	*
+	* @returns An empty series until the backend client is implemented.
+	**/
+	async getHistory(query) {
+		this.#logger?.debug({ query }, "offchain positions history is not implemented, serving empty series");
+		return {
+			result: {
+				metric: query.metric,
+				points: [],
+				metadata: {}
+			},
+			meta: { status: "success" }
+		};
+	}
+};
+//#endregion
+export { OffchainPositions };

package/dist/esm/offchain/positions/index.js

@@ -0,0 +1,2 @@
+import { OffchainPositions } from "./OffchainPositions.js";
+export { OffchainPositions };

package/dist/esm/offchain/types.js

@@ -1 +1,17 @@
-export {};
+//#region src/offchain/types.ts
+/**
+* Thrown by the endpoints that have no stub answer, so that a caller in
+* `offchain` mode fails loudly instead of reading an empty detail page as a
+* missing entity.
+*
+* Lives here rather than in one namespace because every stubbed namespace
+* throws it.
+**/
+var OffchainNotImplementedError = class extends Error {
+	constructor(endpoint) {
+		super(`GearboxAPI: ${endpoint} is not implemented yet`);
+		this.name = "OffchainNotImplementedError";
+	}
+};
+//#endregion
+export { OffchainNotImplementedError };

package/dist/esm/sdk/MultichainSDK.js

@@ -7,6 +7,8 @@ import "./accounts/index.js";
 import "./core/index.js";
 import { MultichainOpportunitiesService } from "./opportunities/MultichainOpportunitiesService.js";
 import "./opportunities/index.js";
+import { MultichainPositionsService } from "./positions/MultichainPositionsService.js";
+import "./positions/index.js";
 import { OnchainSDK } from "./OnchainSDK.js";
 //#region src/sdk/MultichainSDK.ts
 /**
@@ -29,6 +31,10 @@ var MultichainSDK = class {
 	* chains.
 	*/
 	opportunities;
+	/**
+	* Namespace for the positions a wallet holds on all configured chains.
+	*/
+	positions;
 	constructor(options) {
 		this.#chains = /* @__PURE__ */ new Map();
 		this.#logger = options.logger;
@@ -47,6 +53,7 @@ var MultichainSDK = class {
 		}
 		this.liquidations = new MultichainLiquidationsService(this);
 		this.opportunities = new MultichainOpportunitiesService(this);
+		this.positions = new MultichainPositionsService(this);
 	}
 	/**
 	* Attach all configured chains in parallel.

package/dist/esm/sdk/OnchainSDK.js

@@ -30,6 +30,8 @@ import { PluginStateVersionError } from "./plugins/errors.js";
 import "./plugins/index.js";
 import { PoolService } from "./pools/PoolService.js";
 import "./pools/index.js";
+import { PositionsService } from "./positions/PositionsService.js";
+import "./positions/index.js";
 import { createRouter } from "./router/createRouter.js";
 import "./router/index.js";
 import { createPublicClient, fallback, http, parseEventLogs } from "viem";
@@ -112,6 +114,10 @@ var OnchainSDK = class extends ChainContractsRegister {
 	*/
 	opportunities;
 	/**
+	* Namespace for the positions a wallet holds on this chain.
+	*/
+	positions;
+	/**
 	* @param network - Gearbox network type (e.g. `"Mainnet"`, `"Monad"`).
 	* @param clientOptions - Connection options (RPC URLs, transport, or client).
 	* @param options - SDK configuration options.
@@ -133,6 +139,7 @@ var OnchainSDK = class extends ChainContractsRegister {
 		this.pools = new PoolService(this);
 		this.liquidations = new LiquidationsService(this);
 		this.opportunities = new OpportunitiesService(this);
+		this.positions = new PositionsService(this);
 		this.#withdrawalCompressor = createWithdrawalCompressor(this);
 	}
 	/**