@oobe-protocol-labs/sap-mcp-server 0.9.37 → 0.9.38

package/dist/tools/perp-tools.js

@@ -2,10 +2,10 @@
  * @name tools/perp-tools
  * @description MCP tools for perpetual futures trading and chart analysis on Solana.
  *
- * Provides 8 tools across two categories:
+ * Provides perp analytics plus explicit execution-readiness tooling:
  *
  *   Read-only tools (7):
- *     - sap_perp_markets          — List Adrena perp markets with mark price, funding, OI.
+ *     - sap_perp_markets          — List Adrena markets with funding/accounting, OI, and oracle ids.
  *     - sap_perp_position_info    — Read on-chain perp positions for a wallet.
  *     - sap_perp_funding_history  — Compute funding rate from on-chain custody account.
  *     - sap_chart_ohlc            — OHLC candlestick data for any Solana token.
@@ -13,24 +13,28 @@
  *     - sap_chart_volume_profile  — Volume profile analysis (POC, VAH, VAL).
  *     - sap_perp_liquidation_zones — Compute liquidation zones for open positions.
  *
- *   Professional planning tools (1):
+ *   Professional planning tools:
  *     - sap_perp_trade_plan       — Build a trader-grade risk, route, and execution checklist.
+ *     - sap_perp_builder_status   — Report whether a hosted unsigned perps builder is configured.
  *
- * All read-only tools use free APIs (DexScreener, DeFiLlama) and Solana RPC
- * (Triton). Execution builders are intentionally not exposed unless the
- * account graph is IDL-backed and safe for local finalization.
+ * Adrena reads decode Pool, Custody, and Position accounts directly from the
+ * official release/39 ABI layout through Solana RPC. Optional provider hooks
+ * can enrich reads or build unsigned execution transactions, but SAP MCP never
+ * pretends a perps execution route exists until the builder can return a real
+ * locally finalizable Solana transaction.
  *
  * @module tools/perp-tools
  */
 import { PublicKey } from '@solana/web3.js';
+import bs58 from 'bs58';
 import { createTextResponse } from '../adapters/mcp/tool-response.js';
 import { registerTool } from '../adapters/mcp/sdk-compat.js';
 import { logger } from '../core/logger.js';
 /* ═══════════════════════════════════════════════════════════════════
  *  Constants
  * ═══════════════════════════════════════════════════════════════════ */
-/** Adrena program ID on Solana mainnet. */
-const ADRENA_PROGRAM_ID = new PublicKey('13gDzEXCdocbj8iAiqrScGo47NiSuYENGsRqi3SEAwet');
+/** Adrena program ID on Solana mainnet. Can be overridden by hosted env config. */
+const DEFAULT_ADRENA_PROGRAM_ID = '13gDzEXCdocbj8iAiqrScGo47NiSuYENGsRqi3SEAwet';
 /** DexScreener REST API base URL (free, no API key). */
 const DEXSCREENER_API_URL = 'https://api.dexscreener.com';
 /** DeFiLlama REST API base URL (free, no API key). */
@@ -50,6 +54,103 @@ const DISC_POOL = Buffer.from([241, 154, 109, 4, 17, 177, 109, 188]);
 const DISC_CUSTODY = Buffer.from([1, 184, 48, 81, 93, 131, 63, 145]);
 /** Position account discriminator — sha256("account:Position")[0..8]. */
 const DISC_POSITION = Buffer.from([170, 188, 143, 228, 122, 64, 247, 208]);
+/** Adrena release/39 constants from the official ABI. */
+const ADRENA_USD_DECIMALS = 6;
+const ADRENA_PRICE_DECIMALS = 10;
+const ADRENA_BPS_DECIMALS = 4;
+/** Absolute offsets include the 8-byte Anchor account discriminator. */
+const ADRENA_CUSTODY_OFFSETS = {
+    allowTrade: 10,
+    allowSwap: 11,
+    decimals: 12,
+    pool: 16,
+    mint: 48,
+    tokenAccount: 80,
+    oracle: 112,
+    tradeOracle: 144,
+    maxInitialLeverage: 176,
+    maxLeverage: 180,
+    maxPositionLockedUsd: 184,
+    volumeOpenPositionUsd: 320,
+    tradeOiLongUsd: 360,
+    tradeOiShortUsd: 368,
+    assetsCollateral: 376,
+    assetsOwned: 384,
+    assetsLocked: 392,
+    longPositionsOpenCount: 400,
+    longPositionsSizeUsd: 408,
+    longPositionsBorrowSizeUsd: 416,
+    longPositionsLockedAmount: 424,
+    longPositionsCollateralUsd: 472,
+    shortPositionsOpenCount: 600,
+    shortPositionsSizeUsd: 608,
+    shortPositionsBorrowSizeUsd: 616,
+    shortPositionsLockedAmount: 624,
+    shortPositionsCollateralUsd: 672,
+    borrowRateCurrent: 800,
+    borrowRateLastUpdate: 808,
+    optimalUtilizationBps: 832,
+    virtualFundingMaxHourlyRate: 840,
+    virtualFundingMinTotalOiUsd: 848,
+    virtualFundingImbalanceSensitivityBps: 856,
+    virtualFundingCurrentLongToShort: 864,
+    virtualFundingLastUpdate: 872,
+    virtualFundingCumulativeLongToShort: 880,
+    virtualFundingCumulativeShortToLong: 896,
+    isSynthetic: 912,
+    version: 913,
+    oracleFeedId: 914,
+    tradeOracleFeedId: 915,
+};
+const ADRENA_POOL_OFFSETS = {
+    allowTrade: 12,
+    allowSwap: 13,
+    registeredCustodyCount: 15,
+    name: 16,
+    custodies: 48,
+    lpTokenPriceUsd: 328,
+    aumUsd: 448,
+};
+export const ADRENA_POSITION_OWNER_MEMCMP_OFFSET = 16;
+const ADRENA_POSITION_OFFSETS = {
+    side: 9,
+    owner: ADRENA_POSITION_OWNER_MEMCMP_OFFSET,
+    pool: 48,
+    custody: 80,
+    collateralCustody: 112,
+    openTime: 144,
+    updateTime: 152,
+    price: 160,
+    sizeUsd: 168,
+    borrowSizeUsd: 176,
+    collateralUsd: 184,
+    unrealizedInterestUsd: 192,
+    lockedAmount: 216,
+    collateralAmount: 224,
+    exitFeeUsd: 232,
+    liquidationFeeUsd: 240,
+    id: 248,
+    takeProfitLimitPrice: 256,
+    paidInterestUsd: 264,
+    stopLossLimitPrice: 272,
+    stopLossClosePositionPrice: 280,
+    unrealizedFundingPaidUsd: 328,
+    unrealizedFundingReceivedUsd: 336,
+};
+const ADRENA_MAINNET_POOLS = {
+    '4bQRutgDJs6vuh6ZcWaPVXiQaBzbHketjbCDjL4oRN34': { name: 'main-pool', type: 'gmx' },
+    GN2hyBVHcUitWETeDfAoeXDMqow1x8StqdRFnGaUB2vb: { name: 'commodities-pool', type: 'autonom' },
+};
+const ADRENA_MAINNET_MARKETS_BY_CUSTODY = {
+    Dk523LZeDQbZtUwPEBjFXCd2Au1tD7mWZBJJmcgHktNk: { symbol: 'USDC', market: 'USDC', poolName: 'main-pool', kind: 'collateral' },
+    '8aJuzsgjxBnvRhDcfQBD7z4CUj7QoPEpaNwVd7KqsSk5': { symbol: 'BONK', market: 'BONK-PERP', poolName: 'main-pool', kind: 'perp' },
+    GZ9XfWwgTRhkma2Y91Q9r1XKotNXYjBnKKabj19rhT71: { symbol: 'JITOSOL', market: 'JITOSOL-PERP', poolName: 'main-pool', kind: 'perp' },
+    GFu3qS22mo6bAjg4Lr5R7L8pPgHq6GvbjJPKEHkbbs2c: { symbol: 'WBTC', market: 'WBTC-PERP', poolName: 'main-pool', kind: 'perp' },
+    woVG8fmrUzFJhWa6mRjiYC2qFCY73oAnQeioYK1m1JX: { symbol: 'USDC', market: 'USDC', poolName: 'commodities-pool', kind: 'collateral' },
+    JB86ouHXGYgF4UbPs8yxYdaHudrdsintf5EbBfMydzYt: { symbol: 'XAU', market: 'XAU-PERP', poolName: 'commodities-pool', kind: 'synthetic-perp' },
+    De21TFyUPHkvFsWAt6xJLBBXGp636VuL5cKk2DvfbHiR: { symbol: 'WTI', market: 'WTI-PERP', poolName: 'commodities-pool', kind: 'synthetic-perp' },
+    PexsCkkxpVmY4HNxUjT3U9PEg69kYScc8GukUwn6Q3Q: { symbol: 'XAG', market: 'XAG-PERP', poolName: 'commodities-pool', kind: 'synthetic-perp' },
+};
 /* ═══════════════════════════════════════════════════════════════════
  *  Helper: timed fetch
  * ═══════════════════════════════════════════════════════════════════ */
@@ -62,13 +163,14 @@ const DISC_POSITION = Buffer.from([170, 188, 143, 228, 122, 64, 247, 208]);
  *
  * @internal
  */
-async function timedFetch(url) {
+async function timedFetch(url, options = {}) {
     try {
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
+        const timeout = setTimeout(() => controller.abort(), options.timeoutMs ?? FETCH_TIMEOUT_MS);
         const response = await fetch(url, {
-            method: 'GET',
-            headers: { 'Content-Type': 'application/json' },
+            method: options.method ?? 'GET',
+            headers: { 'Content-Type': 'application/json', ...(options.headers ?? {}) },
+            body: options.body,
             signal: controller.signal,
         });
         clearTimeout(timeout);
@@ -80,6 +182,75 @@ async function timedFetch(url) {
         return null;
     }
 }
+function getPerpsConfig(context) {
+    return context.config.perps ?? {
+        adrenaProgramId: DEFAULT_ADRENA_PROGRAM_ID,
+        apiKeyConfigured: Boolean(process.env.SAP_MCP_PERPS_API_KEY?.trim()),
+        timeoutMs: FETCH_TIMEOUT_MS,
+    };
+}
+function getAdrenaProgramId(context) {
+    return new PublicKey(getPerpsConfig(context).adrenaProgramId || DEFAULT_ADRENA_PROGRAM_ID);
+}
+function perpsProviderHeaders() {
+    const apiKey = process.env.SAP_MCP_PERPS_API_KEY?.trim();
+    if (!apiKey) {
+        return {};
+    }
+    return {
+        Authorization: `Bearer ${apiKey}`,
+        'X-API-Key': apiKey,
+    };
+}
+function appendQuery(baseUrl, params) {
+    const url = new URL(baseUrl);
+    for (const [key, value] of Object.entries(params)) {
+        if (value) {
+            url.searchParams.set(key, value);
+        }
+    }
+    return url.toString();
+}
+export function normalizePerpProviderMarkets(payload, marketFilter = '') {
+    const records = Array.isArray(payload)
+        ? payload
+        : payload && typeof payload === 'object' && !Array.isArray(payload)
+            ? (payload.markets ?? payload.data ?? [])
+            : [];
+    const normalized = records
+        .filter((record) => Boolean(record) && typeof record === 'object' && !Array.isArray(record))
+        .map((record) => {
+        const symbol = String(record.symbol ?? record.market ?? '').toUpperCase();
+        return {
+            ...record,
+            symbol,
+            market: String(record.market ?? symbol),
+        };
+    });
+    if (!marketFilter) {
+        return normalized;
+    }
+    return normalized.filter((record) => record.symbol === marketFilter || String(record.market).toUpperCase() === marketFilter);
+}
+async function fetchConfiguredPerpMarkets(context, marketFilter) {
+    const perps = getPerpsConfig(context);
+    if (!perps.marketsUrl) {
+        return null;
+    }
+    const url = appendQuery(perps.marketsUrl, { market: marketFilter || undefined });
+    const payload = await timedFetch(url, {
+        headers: perpsProviderHeaders(),
+        timeoutMs: perps.timeoutMs,
+    });
+    if (!payload) {
+        return null;
+    }
+    return {
+        markets: normalizePerpProviderMarkets(payload, marketFilter),
+        source: Array.isArray(payload) ? 'configured-perps-provider' : payload.source ?? payload.venue ?? 'configured-perps-provider',
+        timestamp: Array.isArray(payload) ? Date.now() : payload.timestamp,
+    };
+}
 /**
  * @name discToBase58
  * @description Convert an 8-byte discriminator Buffer to a base58 string for
@@ -90,8 +261,8 @@ async function timedFetch(url) {
  *
  * @internal
  */
-function discToBase58(disc) {
-    return new PublicKey(disc).toBase58();
+export function discToBase58(disc) {
+    return bs58.encode(disc);
 }
 /**
  * @name readU64LE
@@ -107,28 +278,262 @@ function readU64LE(buf, offset) {
     return Number(buf.readBigUInt64LE(offset));
 }
 /**
- * @name readSymbol
- * @description Read a short string (Anchor `String` — 4-byte LE length + UTF-8 bytes)
+ * @name readI64LE
+ * @description Read an i64 little-endian value from a Buffer and return as a JS number.
+ *
+ * @param buf    — Source buffer.
+ * @param offset — Read offset.
+ * @returns The signed value as a JavaScript number.
+ *
+ * @internal
+ */
+function readI64LE(buf, offset) {
+    return Number(buf.readBigInt64LE(offset));
+}
+function readU128Split(buf, offset) {
+    const high = buf.readBigUInt64LE(offset);
+    const low = buf.readBigUInt64LE(offset + 8);
+    return (high << 64n) + low;
+}
+function readPublicKey(buf, offset) {
+    return new PublicKey(buf.subarray(offset, offset + 32)).toBase58();
+}
+function scaleNumber(raw, decimals) {
+    return Number(raw) / (10 ** decimals);
+}
+function readUsd(buf, offset) {
+    return scaleNumber(buf.readBigUInt64LE(offset), ADRENA_USD_DECIMALS);
+}
+function readPrice(buf, offset) {
+    return scaleNumber(buf.readBigUInt64LE(offset), ADRENA_PRICE_DECIMALS);
+}
+/**
+ * @name readAdrenaLimitedString
+ * @description Read Adrena `LimitedString` (31-byte value + 1-byte length)
  *              from an account data buffer.
  *
  * @param buf    — Source buffer.
- * @param offset — Offset to the string field.
- * @param maxLen — Maximum bytes to read (default 16).
+ * @param offset — Offset to the LimitedString field.
  * @returns Decoded symbol string, or empty string on failure.
  *
  * @internal
  */
-function readSymbol(buf, offset, maxLen = 16) {
+export function readAdrenaLimitedString(buf, offset) {
     try {
-        const len = buf.readUInt32LE(offset);
-        if (len === 0 || len > maxLen)
+        const len = buf[offset + 31] ?? 0;
+        if (len === 0 || len > 31)
             return '';
-        return buf.subarray(offset + 4, offset + 4 + len).toString('utf8').replace(/\0/g, '');
+        return buf.subarray(offset, offset + len).toString('utf8').replace(/\0/g, '').trim();
     }
     catch {
         return '';
     }
 }
+function inferAdrenaSymbolFromOracle(oracle, fallback) {
+    const normalized = oracle.toUpperCase().replace(/[^A-Z0-9]/g, '');
+    for (const candidate of ['JITOSOL', 'WBTC', 'BONK', 'USDC', 'XAU', 'WTI', 'XAG', 'SOL', 'BTC']) {
+        if (normalized.includes(candidate)) {
+            return candidate;
+        }
+    }
+    return fallback;
+}
+function decodeAdrenaPoolAccount(pubkey, data) {
+    if (data.length < ADRENA_POOL_OFFSETS.custodies + 32) {
+        return null;
+    }
+    if (!data.subarray(0, 8).equals(DISC_POOL)) {
+        return null;
+    }
+    const poolAddress = pubkey.toBase58();
+    const registeredCustodyCount = data[ADRENA_POOL_OFFSETS.registeredCustodyCount] ?? 0;
+    const custodies = [];
+    const custodyCount = Math.min(registeredCustodyCount, 8);
+    for (let i = 0; i < custodyCount; i++) {
+        custodies.push(readPublicKey(data, ADRENA_POOL_OFFSETS.custodies + i * 32));
+    }
+    const manifestPool = ADRENA_MAINNET_POOLS[poolAddress];
+    return {
+        poolAddress,
+        name: readAdrenaLimitedString(data, ADRENA_POOL_OFFSETS.name) || manifestPool?.name || 'unknown-pool',
+        type: manifestPool?.type,
+        allowTrade: data[ADRENA_POOL_OFFSETS.allowTrade] !== 0,
+        allowSwap: data[ADRENA_POOL_OFFSETS.allowSwap] !== 0,
+        registeredCustodyCount,
+        custodies,
+        lpTokenPriceUsd: readUsd(data, ADRENA_POOL_OFFSETS.lpTokenPriceUsd),
+        aumUsd: scaleNumber(readU128Split(data, ADRENA_POOL_OFFSETS.aumUsd), ADRENA_USD_DECIMALS),
+    };
+}
+export function decodeAdrenaCustodyAccount(pubkey, data, pool) {
+    if (data.length < ADRENA_CUSTODY_OFFSETS.version + 1) {
+        return null;
+    }
+    if (!data.subarray(0, 8).equals(DISC_CUSTODY)) {
+        return null;
+    }
+    const custodyAddress = pubkey.toBase58();
+    const manifest = ADRENA_MAINNET_MARKETS_BY_CUSTODY[custodyAddress];
+    const poolAddress = readPublicKey(data, ADRENA_CUSTODY_OFFSETS.pool);
+    const custodyMint = readPublicKey(data, ADRENA_CUSTODY_OFFSETS.mint);
+    const oracle = readAdrenaLimitedString(data, ADRENA_CUSTODY_OFFSETS.oracle);
+    const tradeOracle = readAdrenaLimitedString(data, ADRENA_CUSTODY_OFFSETS.tradeOracle);
+    const inferredSymbol = inferAdrenaSymbolFromOracle(tradeOracle || oracle, custodyMint.slice(0, 6).toUpperCase());
+    const symbol = manifest?.symbol ?? inferredSymbol;
+    const isSynthetic = data[ADRENA_CUSTODY_OFFSETS.isSynthetic] !== 0;
+    const kind = manifest?.kind ?? (isSynthetic ? 'synthetic-perp' : 'unknown');
+    return {
+        symbol,
+        market: manifest?.market ?? (kind === 'collateral' ? symbol : `${symbol}-PERP`),
+        custodyAddress,
+        poolAddress,
+        poolName: pool?.name ?? manifest?.poolName ?? ADRENA_MAINNET_POOLS[poolAddress]?.name,
+        poolType: pool?.type ?? ADRENA_MAINNET_POOLS[poolAddress]?.type,
+        custodyMint,
+        tokenAccount: readPublicKey(data, ADRENA_CUSTODY_OFFSETS.tokenAccount),
+        oracle,
+        tradeOracle,
+        oracleFeedId: data[ADRENA_CUSTODY_OFFSETS.oracleFeedId] ?? 0,
+        tradeOracleFeedId: data[ADRENA_CUSTODY_OFFSETS.tradeOracleFeedId] ?? 0,
+        decimals: data[ADRENA_CUSTODY_OFFSETS.decimals] ?? 0,
+        allowTrade: data[ADRENA_CUSTODY_OFFSETS.allowTrade] !== 0,
+        allowSwap: data[ADRENA_CUSTODY_OFFSETS.allowSwap] !== 0,
+        isStable: data[13] !== 0,
+        isSynthetic,
+        version: data[ADRENA_CUSTODY_OFFSETS.version] ?? 0,
+        kind,
+        markPrice: null,
+        markPriceSource: 'not_in_custody_account',
+        maxInitialLeverage: data.readUInt32LE(ADRENA_CUSTODY_OFFSETS.maxInitialLeverage) / (10 ** ADRENA_BPS_DECIMALS),
+        maxLeverage: data.readUInt32LE(ADRENA_CUSTODY_OFFSETS.maxLeverage) / (10 ** ADRENA_BPS_DECIMALS),
+        maxPositionLockedUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.maxPositionLockedUsd),
+        openInterestLong: readUsd(data, ADRENA_CUSTODY_OFFSETS.longPositionsSizeUsd),
+        openInterestShort: readUsd(data, ADRENA_CUSTODY_OFFSETS.shortPositionsSizeUsd),
+        openPositionsLong: readU64LE(data, ADRENA_CUSTODY_OFFSETS.longPositionsOpenCount),
+        openPositionsShort: readU64LE(data, ADRENA_CUSTODY_OFFSETS.shortPositionsOpenCount),
+        borrowSizeLongUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.longPositionsBorrowSizeUsd),
+        borrowSizeShortUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.shortPositionsBorrowSizeUsd),
+        collateralLongUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.longPositionsCollateralUsd),
+        collateralShortUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.shortPositionsCollateralUsd),
+        lockedAmountLongRaw: data.readBigUInt64LE(ADRENA_CUSTODY_OFFSETS.longPositionsLockedAmount).toString(),
+        lockedAmountShortRaw: data.readBigUInt64LE(ADRENA_CUSTODY_OFFSETS.shortPositionsLockedAmount).toString(),
+        tradeOiLongUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.tradeOiLongUsd),
+        tradeOiShortUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.tradeOiShortUsd),
+        cumulativeOpenPositionUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.volumeOpenPositionUsd),
+        assetsRaw: {
+            collateral: data.readBigUInt64LE(ADRENA_CUSTODY_OFFSETS.assetsCollateral).toString(),
+            owned: data.readBigUInt64LE(ADRENA_CUSTODY_OFFSETS.assetsOwned).toString(),
+            locked: data.readBigUInt64LE(ADRENA_CUSTODY_OFFSETS.assetsLocked).toString(),
+        },
+        borrowRate: {
+            currentRateRaw: data.readBigUInt64LE(ADRENA_CUSTODY_OFFSETS.borrowRateCurrent).toString(),
+            lastUpdate: readI64LE(data, ADRENA_CUSTODY_OFFSETS.borrowRateLastUpdate),
+        },
+        funding: {
+            currentRateLongToShortRaw: data.readBigInt64LE(ADRENA_CUSTODY_OFFSETS.virtualFundingCurrentLongToShort).toString(),
+            lastUpdate: readI64LE(data, ADRENA_CUSTODY_OFFSETS.virtualFundingLastUpdate),
+            cumulativeLongToShortRaw: readU128Split(data, ADRENA_CUSTODY_OFFSETS.virtualFundingCumulativeLongToShort).toString(),
+            cumulativeShortToLongRaw: readU128Split(data, ADRENA_CUSTODY_OFFSETS.virtualFundingCumulativeShortToLong).toString(),
+            maxHourlyFundingRateRaw: data.readBigUInt64LE(ADRENA_CUSTODY_OFFSETS.virtualFundingMaxHourlyRate).toString(),
+            minTotalOiUsd: readUsd(data, ADRENA_CUSTODY_OFFSETS.virtualFundingMinTotalOiUsd),
+            imbalanceSensitivityBps: data.readUInt16LE(ADRENA_CUSTODY_OFFSETS.virtualFundingImbalanceSensitivityBps),
+        },
+    };
+}
+function sideFromAdrenaByte(sideByte) {
+    if (sideByte === 1)
+        return 'long';
+    if (sideByte === 2)
+        return 'short';
+    return null;
+}
+export function decodeAdrenaPositionAccount(pubkey, data, marketsByCustody = new Map()) {
+    if (data.length < ADRENA_POSITION_OFFSETS.unrealizedFundingReceivedUsd + 8) {
+        return null;
+    }
+    if (!data.subarray(0, 8).equals(DISC_POSITION)) {
+        return null;
+    }
+    const sideRaw = data[ADRENA_POSITION_OFFSETS.side] ?? 0;
+    const side = sideFromAdrenaByte(sideRaw);
+    if (!side) {
+        return null;
+    }
+    const custodyAddress = readPublicKey(data, ADRENA_POSITION_OFFSETS.custody);
+    const market = marketsByCustody.get(custodyAddress)?.market ?? 'unknown';
+    const entryPrice = readPrice(data, ADRENA_POSITION_OFFSETS.price);
+    const sizeUsd = readUsd(data, ADRENA_POSITION_OFFSETS.sizeUsd);
+    const collateralUsd = readUsd(data, ADRENA_POSITION_OFFSETS.collateralUsd);
+    const leverage = collateralUsd > 0 ? sizeUsd / collateralUsd : 0;
+    const liquidationPrice = leverage > 0
+        ? side === 'long'
+            ? entryPrice * (1 - 1 / leverage)
+            : entryPrice * (1 + 1 / leverage)
+        : 0;
+    const takeProfitLimitPrice = readPrice(data, ADRENA_POSITION_OFFSETS.takeProfitLimitPrice);
+    const stopLossLimitPrice = readPrice(data, ADRENA_POSITION_OFFSETS.stopLossLimitPrice);
+    const stopLossClosePositionPrice = readPrice(data, ADRENA_POSITION_OFFSETS.stopLossClosePositionPrice);
+    return {
+        positionKey: pubkey.toBase58(),
+        market,
+        side,
+        sideRaw,
+        owner: readPublicKey(data, ADRENA_POSITION_OFFSETS.owner),
+        poolAddress: readPublicKey(data, ADRENA_POSITION_OFFSETS.pool),
+        custodyAddress,
+        collateralCustodyAddress: readPublicKey(data, ADRENA_POSITION_OFFSETS.collateralCustody),
+        openTime: readI64LE(data, ADRENA_POSITION_OFFSETS.openTime),
+        updateTime: readI64LE(data, ADRENA_POSITION_OFFSETS.updateTime),
+        entryPrice,
+        entryPriceRaw: data.readBigUInt64LE(ADRENA_POSITION_OFFSETS.price).toString(),
+        size: sizeUsd,
+        collateral: collateralUsd,
+        borrowSizeUsd: readUsd(data, ADRENA_POSITION_OFFSETS.borrowSizeUsd),
+        leverage,
+        unrealizedPnl: 0,
+        unrealizedInterestUsd: readUsd(data, ADRENA_POSITION_OFFSETS.unrealizedInterestUsd),
+        unrealizedFundingPaidUsd: readUsd(data, ADRENA_POSITION_OFFSETS.unrealizedFundingPaidUsd),
+        unrealizedFundingReceivedUsd: readUsd(data, ADRENA_POSITION_OFFSETS.unrealizedFundingReceivedUsd),
+        lockedAmountRaw: data.readBigUInt64LE(ADRENA_POSITION_OFFSETS.lockedAmount).toString(),
+        collateralAmountRaw: data.readBigUInt64LE(ADRENA_POSITION_OFFSETS.collateralAmount).toString(),
+        liquidationPrice,
+        takeProfitLimitPrice: takeProfitLimitPrice > 0 ? takeProfitLimitPrice : null,
+        stopLossLimitPrice: stopLossLimitPrice > 0 ? stopLossLimitPrice : null,
+        stopLossClosePositionPrice: stopLossClosePositionPrice > 0 ? stopLossClosePositionPrice : null,
+        id: data.readBigUInt64LE(ADRENA_POSITION_OFFSETS.id).toString(),
+    };
+}
+async function readAdrenaMarketsByCustody(context) {
+    const adrenaProgramId = getAdrenaProgramId(context);
+    const [poolAccounts, custodyAccounts] = await Promise.all([
+        context.connection.getProgramAccounts(adrenaProgramId, {
+            filters: [{ memcmp: { offset: 0, bytes: discToBase58(DISC_POOL) } }],
+            commitment: 'confirmed',
+        }),
+        context.connection.getProgramAccounts(adrenaProgramId, {
+            filters: [{ memcmp: { offset: 0, bytes: discToBase58(DISC_CUSTODY) } }],
+            commitment: 'confirmed',
+        }),
+    ]);
+    const pools = new Map();
+    for (const { pubkey, account } of poolAccounts) {
+        const decoded = decodeAdrenaPoolAccount(pubkey, account.data);
+        if (decoded) {
+            pools.set(decoded.poolAddress, decoded);
+        }
+    }
+    const markets = new Map();
+    for (const { pubkey, account } of custodyAccounts) {
+        const poolAddress = account.data.length >= ADRENA_CUSTODY_OFFSETS.pool + 32
+            ? readPublicKey(account.data, ADRENA_CUSTODY_OFFSETS.pool)
+            : '';
+        const decoded = decodeAdrenaCustodyAccount(pubkey, account.data, pools.get(poolAddress));
+        if (decoded) {
+            markets.set(decoded.custodyAddress, decoded);
+        }
+    }
+    return markets;
+}
 /* ═══════════════════════════════════════════════════════════════════
  *  Tool 1: sap_perp_markets
  * ═══════════════════════════════════════════════════════════════════ */
@@ -157,132 +562,115 @@ function registerPerpMarketsTool(server, context) {
         additionalProperties: false,
     };
     registerTool(server, 'sap_perp_markets', {
-        description: 'List available perpetual futures markets from Adrena Pool/Custody accounts with mark price, funding rate, open interest, and 24h volume when the configured RPC can serve the required account indexes. Read-only analysis tool. If markets are empty, treat it as data unavailable, not proof that markets do not exist. SAP MCP currently exposes no hosted Adrena execution builder; use sap_perp_trade_plan plus chart tools for planning only.',
+        description: 'List available Adrena perpetual futures markets from Pool/Custody accounts with funding/accounting fields, open interest, leverage caps, and oracle identifiers. Read-only analysis tool. Custody accounts do not expose a ready mark price, so markPrice is null until an oracle/feed decoder or configured Adrena data runtime is available. If markets are empty, treat it as data unavailable, not proof that markets do not exist. SAP MCP exposes execution only when sap_perp_builder_status reports a verified hosted unsigned builder.',
         inputSchema: schema,
     }, async (args) => {
         const marketFilter = typeof args['market'] === 'string' ? args['market'].toUpperCase() : '';
         try {
+            const providerMarkets = await fetchConfiguredPerpMarkets(context, marketFilter);
+            if (providerMarkets) {
+                return createTextResponse(JSON.stringify({
+                    source: providerMarkets.source,
+                    markets: providerMarkets.markets,
+                    count: providerMarkets.markets.length,
+                    timestamp: providerMarkets.timestamp ?? Date.now(),
+                    dataAvailability: {
+                        status: providerMarkets.markets.length > 0 ? 'available' : 'empty_from_provider',
+                        reason: providerMarkets.markets.length > 0
+                            ? 'Configured perps market provider returned market data.'
+                            : 'Configured perps market provider responded but returned no matching markets for the requested filter.',
+                        agentAction: providerMarkets.markets.length > 0
+                            ? 'Use these records for professional planning. Before execution, call sap_perp_builder_status to verify whether a hosted unsigned builder is configured.'
+                            : 'Do not infer that the venue has no markets. Try a broader market filter or check provider status before planning execution.',
+                    },
+                    recommendedNextTools: [
+                        'sap_perp_builder_status',
+                        'sap_chart_ohlc',
+                        'sap_chart_volume_profile',
+                        'sap_perp_trade_plan',
+                    ],
+                    executionStatus: getPerpsConfig(context).builderUrl
+                        ? 'hosted_unsigned_builder_configured'
+                        : 'analysis_only_no_hosted_builder',
+                    note: 'Market data came from the configured hosted perps provider, not heuristic account decoding. Execution still requires a typed unsigned builder and local finalization.',
+                }, null, 2));
+            }
+            const adrenaProgramId = getAdrenaProgramId(context);
             // Fetch Custody accounts — these contain per-token price, funding rate, and OI.
             // We use memcmp on the first 8 bytes (Anchor account discriminator).
-            const custodyAccounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
+            const custodyAccounts = await context.connection.getProgramAccounts(adrenaProgramId, {
                 filters: [
                     { memcmp: { offset: 0, bytes: discToBase58(DISC_CUSTODY) } },
                 ],
                 commitment: 'confirmed',
             });
             // Fetch Pool accounts — these contain pool configuration and token info.
-            const poolAccounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
+            const poolAccounts = await context.connection.getProgramAccounts(adrenaProgramId, {
                 filters: [
                     { memcmp: { offset: 0, bytes: discToBase58(DISC_POOL) } },
                 ],
                 commitment: 'confirmed',
             });
-            // Build a map of pool addresses for cross-referencing.
-            const poolAddresses = new Set(poolAccounts.map(({ pubkey }) => pubkey.toBase58()));
-            // Decode custody accounts into market data.
-            // Custody layout (simplified, after 8-byte discriminator):
-            //   pool(32) + custodyMint(32) + symbol(String: 4+len) + decimals(u8) +
-            //   ... + pricing data (price u64, fundingRate u64, openInterestLong u64, openInterestShort u64, ...)
-            // The exact offsets may vary by IDL version; we attempt common layouts.
-            const markets = [];
-            for (const { pubkey, account } of custodyAccounts) {
-                const data = account.data;
-                if (data.length < 8 + 32 + 32 + 4)
-                    continue;
-                // After discriminator(8): pool(32) + custodyMint(32) = offset 72
-                const poolPubkey = new PublicKey(data.subarray(8, 8 + 32));
-                const custodyMint = new PublicKey(data.subarray(8 + 32, 8 + 64));
-                const poolAddress = poolPubkey.toBase58();
-                // Try to read symbol at offset 72 (after pool + custodyMint).
-                // Anchor String = 4-byte LE length + UTF-8 bytes.
-                let symbol = readSymbol(data, 8 + 64, 16);
-                // Try alternative offsets if symbol is empty (layout may differ).
-                if (!symbol) {
-                    // Try after pool(32) only — some IDL versions place symbol before custodyMint.
-                    symbol = readSymbol(data, 8 + 32, 16);
+            const poolInfoByAddress = new Map();
+            for (const { pubkey, account } of poolAccounts) {
+                const decoded = decodeAdrenaPoolAccount(pubkey, account.data);
+                if (decoded) {
+                    poolInfoByAddress.set(decoded.poolAddress, decoded);
                 }
-                // Read decimals (u8) — typically right after the symbol string.
-                // We try offset after symbol, but since symbol length varies, we also
-                // try fixed offsets as fallback.
-                let decimals = 6;
-                const symbolEndOffset = 8 + 64 + 4 + (symbol ? symbol.length : 0);
-                if (symbolEndOffset < data.length) {
-                    const dec = data[symbolEndOffset];
-                    if (dec > 0 && dec <= 18)
-                        decimals = dec;
-                }
-                // Price and funding data: attempt to read from deeper in the account.
-                // Common Adrena Custody layout has pricing fields after config section.
-                // We try multiple offsets; if reads fail, default to 0.
-                // Pricing section typically starts around offset 120-200 depending on symbol length.
-                let markPrice = 0;
-                let fundingRate = 0;
-                let openInterestLong = 0;
-                let openInterestShort = 0;
-                // Try reading price/funding at various known offsets.
-                // Adrena Custody has: ... config fields ... then pricing struct with:
-                //   price(u64) + fundingRate(u64) + openInterestLong(u64) + openInterestShort(u64)
-                // We scan for plausible price data.
-                for (const baseOffset of [120, 144, 160, 176, 192, 200, 208, 224, 240]) {
-                    if (baseOffset + 32 > data.length)
-                        continue;
-                    const price = readU64LE(data, baseOffset);
-                    const funding = readU64LE(data, baseOffset + 8);
-                    const oiLong = readU64LE(data, baseOffset + 16);
-                    const oiShort = readU64LE(data, baseOffset + 24);
-                    // Heuristic: price should be a reasonable value (> 0, not absurdly large)
-                    // and funding should be small relative to price.
-                    if (price > 0 && price < 1e15 && Math.abs(funding) < price) {
-                        markPrice = price;
-                        fundingRate = funding;
-                        openInterestLong = oiLong;
-                        openInterestShort = oiShort;
-                        break;
-                    }
-                }
-                const marketEntry = {
-                    symbol: symbol || 'UNKNOWN',
-                    custodyAddress: pubkey.toBase58(),
-                    poolAddress,
-                    custodyMint: custodyMint.toBase58(),
-                    markPrice,
-                    fundingRate,
-                    openInterestLong,
-                    openInterestShort,
-                    decimals,
-                    inPool: poolAddresses.has(poolAddress),
-                };
-                markets.push(marketEntry);
             }
+            const markets = custodyAccounts
+                .map(({ pubkey, account }) => {
+                const poolAddress = account.data.length >= ADRENA_CUSTODY_OFFSETS.pool + 32
+                    ? readPublicKey(account.data, ADRENA_CUSTODY_OFFSETS.pool)
+                    : '';
+                return decodeAdrenaCustodyAccount(pubkey, account.data, poolInfoByAddress.get(poolAddress));
+            })
+                .filter((market) => Boolean(market));
             // Apply market filter if provided.
             const filtered = marketFilter
-                ? markets.filter(m => m.symbol.toUpperCase() === marketFilter)
+                ? markets.filter(m => m.symbol.toUpperCase() === marketFilter || m.market.toUpperCase() === marketFilter)
                 : markets;
-            const dataAvailability = custodyAccounts.length === 0 && poolAccounts.length === 0
+            const scannedAccounts = custodyAccounts.length + poolAccounts.length;
+            const dataAvailability = scannedAccounts === 0
                 ? {
-                    status: 'unavailable',
-                    reason: 'No Adrena Pool/Custody accounts were returned by the configured Solana RPC. This can mean the RPC does not serve the required getProgramAccounts index, the upstream account layout changed, or Adrena markets are unavailable for this route.',
-                    agentAction: 'Do not infer that no perp markets exist and do not retry in a loop. Use sap_chart_ohlc/sap_chart_volume_profile for market context, then stop before execution until an IDL-backed builder or native venue route is available.',
+                    status: 'rpc_scan_empty',
+                    reason: 'No configured perps provider is set and no Adrena Pool/Custody accounts were returned by getProgramAccounts using Anchor account discriminators. On an indexed/full-history RPC this usually means the program ID or account type discriminators are stale, not that perps do not exist.',
+                    agentAction: 'Do not infer that no perp markets exist and do not retry in a loop. Operator should verify ADRENA_PROGRAM_ID and account discriminators against the current deployed program/IDL, or configure SAP_MCP_PERPS_MARKETS_URL with an IDL-backed provider. Use sap_chart_ohlc/sap_chart_volume_profile for market context, then stop before execution until sap_perp_builder_status says a builder is available.',
                 }
-                : {
-                    status: 'available',
-                    reason: 'Adrena account scan returned on-chain accounts from the configured RPC.',
-                    agentAction: 'Use custodyAddress and poolAddress only for analysis. SAP MCP does not expose a hosted Adrena execution builder yet.',
-                };
+                : filtered.length === 0
+                    ? {
+                        status: 'decoded_no_matching_markets',
+                        reason: 'The configured RPC returned Adrena Pool/Custody accounts, but no decoded market matched the requested filter. This is usually a market-filter issue.',
+                        agentAction: 'Retry once with an empty market filter to inspect all decoded symbols. If markets decode but markPrice is null, use oracle/chart tools for live price and do not pretend custody contains a spot mark price.',
+                    }
+                    : {
+                        status: 'available',
+                        reason: 'Adrena account scan returned on-chain accounts from the configured RPC.',
+                        agentAction: 'Use custodyAddress and poolAddress only for analysis. Call sap_perp_builder_status before any execution attempt.',
+                    };
             return createTextResponse(JSON.stringify({
                 source: 'on-chain-rpc',
                 markets: filtered,
                 count: filtered.length,
                 totalCustodies: custodyAccounts.length,
                 totalPools: poolAccounts.length,
+                scan: {
+                    programId: adrenaProgramId.toBase58(),
+                    custodyDiscriminator: discToBase58(DISC_CUSTODY),
+                    poolDiscriminator: discToBase58(DISC_POOL),
+                },
                 dataAvailability,
                 recommendedNextTools: [
+                    'sap_perp_builder_status',
                     'sap_chart_ohlc',
                     'sap_chart_volume_profile',
                     'sap_perp_trade_plan',
                 ],
-                executionStatus: 'analysis_only_no_hosted_builder',
-                note: 'Data read directly from Solana on-chain Pool/Custody accounts. Use custodyAddress and poolAddress for analysis only. Do not execute perps unless SAP MCP exposes a typed unsigned builder or a local signer tool for that exact action.',
+                executionStatus: getPerpsConfig(context).builderUrl
+                    ? 'hosted_unsigned_builder_configured'
+                    : 'analysis_only_no_hosted_builder',
+                priceNote: 'Adrena Custody accounts expose market configuration, OI, funding/accounting, and oracle identifiers. They do not expose a ready-to-use mark price. markPrice is null until SAP MCP adds a typed oracle/feed decoder or configured Adrena data runtime.',
+                note: 'Data read directly from Solana on-chain Pool/Custody accounts using the official Adrena release/39 ABI layout. Use custodyAddress and poolAddress for analysis only. Do not execute perps unless SAP MCP exposes a typed unsigned builder or a local signer tool for that exact action.',
             }));
         }
         catch (err) {
@@ -321,7 +709,7 @@ function registerPerpPositionInfoTool(server, context) {
         additionalProperties: false,
     };
     registerTool(server, 'sap_perp_position_info', {
-        description: 'Read all open perpetual positions on Adrena for a given wallet address. Returns position key, market, side, size, collateral, entry price, mark price, leverage, unrealized PnL, and liquidation price. Read-only — uses Solana RPC.',
+        description: 'Read all open perpetual positions on Adrena for a given wallet address. Returns position key, market, side, size, collateral, entry price, leverage, unrealized PnL, and liquidation price from the on-chain Position account. markPrice mirrors entryPrice until SAP MCP has a live oracle/feed price decoder. Read-only — uses Solana RPC.',
         inputSchema: schema,
     }, async (args) => {
         const walletStr = typeof args['wallet'] === 'string' ? args['wallet'] : '';
@@ -336,44 +724,39 @@ function registerPerpPositionInfoTool(server, context) {
             return createTextResponse(JSON.stringify({ error: 'Invalid wallet address' }), { isError: true });
         }
         try {
-            // Adrena Position accounts: filter by Position discriminator + memcmp on owner.
-            // Position layout (from IDL, after 8-byte discriminator):
-            //   owner(32) + pool(32) + custody(32) + side(1) + price(u64) + sizeUsd(u64) + collateralUsd(u64) + ...
-            const accounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
+            const accounts = await context.connection.getProgramAccounts(getAdrenaProgramId(context), {
                 filters: [
                     { memcmp: { offset: 0, bytes: discToBase58(DISC_POSITION) } },
-                    { memcmp: { offset: 8, bytes: walletPubkey.toBase58() } },
+                    { memcmp: { offset: ADRENA_POSITION_OWNER_MEMCMP_OFFSET, bytes: walletPubkey.toBase58() } },
                 ],
                 commitment: 'confirmed',
             });
-            const positions = accounts.map(({ pubkey, account }) => {
-                const data = account.data;
-                // Position layout (from IDL): owner(32) + pool(32) + custody(32) + side(1) + price(u64) + sizeUsd(u64) + collateralUsd(u64) + collateralAmount(u64) + ...
-                const sideByte = data[8 + 32 + 32 + 32];
-                const side = sideByte === 0 ? 'long' : 'short';
-                const price = Number(data.readBigUInt64LE(8 + 32 + 32 + 32 + 1));
-                const sizeUsd = Number(data.readBigUInt64LE(8 + 32 + 32 + 32 + 1 + 8));
-                const collateralUsd = Number(data.readBigUInt64LE(8 + 32 + 32 + 32 + 1 + 8 + 8));
-                const leverage = collateralUsd > 0 ? sizeUsd / collateralUsd : 0;
-                const unrealizedPnl = 0;
-                const liquidationPrice = leverage > 0 ? price * (1 - 1 / leverage) : 0;
-                return {
-                    positionKey: pubkey.toBase58(),
-                    market: 'unknown',
-                    side,
-                    size: sizeUsd,
-                    collateral: collateralUsd,
-                    entryPrice: price,
-                    markPrice: price,
-                    leverage,
-                    unrealizedPnl,
-                    liquidationPrice,
-                };
-            });
+            const marketsByCustody = await readAdrenaMarketsByCustody(context);
+            const positions = accounts
+                .map(({ pubkey, account }) => decodeAdrenaPositionAccount(pubkey, account.data, marketsByCustody))
+                .filter((position) => Boolean(position))
+                .map((position) => ({
+                positionKey: position.positionKey,
+                market: position.market,
+                side: position.side,
+                size: position.size,
+                collateral: position.collateral,
+                entryPrice: position.entryPrice,
+                markPrice: position.entryPrice,
+                leverage: position.leverage,
+                unrealizedPnl: position.unrealizedPnl,
+                liquidationPrice: position.liquidationPrice,
+            }));
             return createTextResponse(JSON.stringify({
                 wallet: walletStr,
                 positions,
                 count: positions.length,
+                scan: {
+                    programId: getAdrenaProgramId(context).toBase58(),
+                    positionDiscriminator: discToBase58(DISC_POSITION),
+                    ownerMemcmpOffset: ADRENA_POSITION_OWNER_MEMCMP_OFFSET,
+                },
+                note: 'Positions are decoded from the official Adrena release/39 Position account layout. markPrice mirrors entryPrice until a live oracle/feed price decoder is available.',
             }));
         }
         catch (err) {
@@ -474,61 +857,51 @@ function registerPerpFundingHistoryTool(server, context) {
                     message: 'The provided address is not a Custody account. Use sap_perp_markets to get the correct custodyAddress.',
                 }), { isError: true });
             }
-            // Decode funding-related fields from the Custody account.
-            // Pool(32) + custodyMint(32) are at offset 8.
-            const poolPubkey = new PublicKey(data.subarray(8, 8 + 32));
-            const custodyMint = new PublicKey(data.subarray(8 + 32, 8 + 64));
-            // Read symbol at offset 72 (after pool + custodyMint).
-            let symbol = readSymbol(data, 8 + 64, 16);
-            if (!symbol) {
-                symbol = readSymbol(data, 8 + 32, 16);
+            const poolAddress = readPublicKey(data, ADRENA_CUSTODY_OFFSETS.pool);
+            const poolsByAddress = new Map();
+            const poolInfo = await context.connection.getAccountInfo(new PublicKey(poolAddress), 'confirmed');
+            if (poolInfo) {
+                const decodedPool = decodeAdrenaPoolAccount(new PublicKey(poolAddress), poolInfo.data);
+                if (decodedPool)
+                    poolsByAddress.set(poolAddress, decodedPool);
             }
-            // Scan for funding rate data at common offsets.
-            let markPrice = 0;
-            let fundingRate = 0;
-            let openInterestLong = 0;
-            let openInterestShort = 0;
-            let cumulativeFunding = 0;
-            for (const baseOffset of [120, 144, 160, 176, 192, 200, 208, 224, 240, 256]) {
-                if (baseOffset + 48 > data.length)
-                    continue;
-                const price = readU64LE(data, baseOffset);
-                const funding = readU64LE(data, baseOffset + 8);
-                const oiLong = readU64LE(data, baseOffset + 16);
-                const oiShort = readU64LE(data, baseOffset + 24);
-                const cumFunding = readU64LE(data, baseOffset + 32);
-                if (price > 0 && price < 1e15 && Math.abs(funding) < price) {
-                    markPrice = price;
-                    fundingRate = funding;
-                    openInterestLong = oiLong;
-                    openInterestShort = oiShort;
-                    cumulativeFunding = cumFunding;
-                    break;
-                }
+            const decoded = decodeAdrenaCustodyAccount(custodyPubkey, data, poolsByAddress.get(poolAddress));
+            if (!decoded) {
+                return createTextResponse(JSON.stringify({
+                    error: 'Unable to decode Adrena Custody account with release/39 ABI layout',
+                    custodyAddress: custodyAddressStr,
+                }), { isError: true });
             }
             const timestamp = Date.now();
             return createTextResponse(JSON.stringify({
                 source: 'on-chain-rpc',
                 custodyAddress: custodyAddressStr,
-                market: market || symbol || 'UNKNOWN',
-                symbol: symbol || 'UNKNOWN',
-                poolAddress: poolPubkey.toBase58(),
-                custodyMint: custodyMint.toBase58(),
+                market: market || decoded.market,
+                symbol: decoded.symbol,
+                poolAddress: decoded.poolAddress,
+                custodyMint: decoded.custodyMint,
+                oracle: decoded.oracle,
+                tradeOracle: decoded.tradeOracle,
                 currentFunding: {
                     timestamp,
-                    fundingRate,
-                    cumulativeFunding,
-                    markPrice,
-                    openInterestLong,
-                    openInterestShort,
+                    fundingRateRaw: decoded.funding.currentRateLongToShortRaw,
+                    cumulativeLongToShortRaw: decoded.funding.cumulativeLongToShortRaw,
+                    cumulativeShortToLongRaw: decoded.funding.cumulativeShortToLongRaw,
+                    maxHourlyFundingRateRaw: decoded.funding.maxHourlyFundingRateRaw,
+                    fundingLastUpdate: decoded.funding.lastUpdate,
+                    markPrice: decoded.markPrice,
+                    markPriceSource: decoded.markPriceSource,
+                    openInterestLong: decoded.openInterestLong,
+                    openInterestShort: decoded.openInterestShort,
                 },
                 records: [{
                         timestamp,
-                        fundingRate,
-                        cumulativeFunding,
+                        fundingRateRaw: decoded.funding.currentRateLongToShortRaw,
+                        cumulativeLongToShortRaw: decoded.funding.cumulativeLongToShortRaw,
+                        cumulativeShortToLongRaw: decoded.funding.cumulativeShortToLongRaw,
                     }],
                 count: 1,
-                note: 'On-chain data provides the current funding snapshot only. Historical time-series funding data is not available via Solana RPC — use sap_perp_markets to monitor funding rate changes over time.',
+                note: 'On-chain Adrena Custody data provides the current funding/accounting snapshot only. Historical time-series funding data is not available via Solana RPC; use repeated snapshots or an indexed Adrena data runtime for history.',
             }));
         }
         catch (err) {
@@ -879,7 +1252,8 @@ function registerChartVolumeProfileTool(server, _context) {
  * @description Register the sap_perp_liquidation_zones read-only tool.
  *
  * Reads on-chain Adrena positions for a wallet and computes liquidation
- * zones based on leverage, collateral, and current mark price.
+ * zones from account geometry. Live current price requires a separate
+ * oracle/feed decoder.
  *
  * @param server  — MCP server instance.
  * @param context — Runtime context with Solana RPC connection.
@@ -899,7 +1273,7 @@ function registerPerpLiquidationZonesTool(server, context) {
         additionalProperties: false,
     };
     registerTool(server, 'sap_perp_liquidation_zones', {
-        description: 'Compute liquidation zones for all open Adrena perp positions of a wallet. Reads on-chain positions via Solana RPC and calculates liquidation price, current price, and distance to liquidation. Read-only.',
+        description: 'Compute liquidation zones for all open Adrena perp positions of a wallet. Reads on-chain positions via Solana RPC and calculates liquidation geometry from entry price, leverage, and liquidation price. currentPrice mirrors entryPrice until SAP MCP has a live oracle/feed price decoder. Read-only.',
         inputSchema: schema,
     }, async (args) => {
         const walletStr = typeof args['wallet'] === 'string' ? args['wallet'] : '';
@@ -914,45 +1288,42 @@ function registerPerpLiquidationZonesTool(server, context) {
             return createTextResponse(JSON.stringify({ error: 'Invalid wallet address' }), { isError: true });
         }
         try {
-            const accounts = await context.connection.getProgramAccounts(ADRENA_PROGRAM_ID, {
+            const accounts = await context.connection.getProgramAccounts(getAdrenaProgramId(context), {
                 filters: [
                     { memcmp: { offset: 0, bytes: discToBase58(DISC_POSITION) } },
-                    { memcmp: { offset: 8, bytes: walletPubkey.toBase58() } },
+                    { memcmp: { offset: ADRENA_POSITION_OWNER_MEMCMP_OFFSET, bytes: walletPubkey.toBase58() } },
                 ],
                 commitment: 'confirmed',
             });
-            const zones = accounts.map(({ pubkey, account }) => {
-                const data = account.data;
-                const sideByte = data[8 + 32 + 32 + 32];
-                const side = sideByte === 0 ? 'long' : 'short';
-                const entryPrice = Number(data.readBigUInt64LE(8 + 32 + 32 + 32 + 1));
-                const sizeUsd = Number(data.readBigUInt64LE(8 + 32 + 32 + 32 + 1 + 8));
-                const collateralUsd = Number(data.readBigUInt64LE(8 + 32 + 32 + 32 + 1 + 8 + 8));
-                const leverage = collateralUsd > 0 ? sizeUsd / collateralUsd : 0;
-                // Liquidation price: for long, price drops by 1/leverage; for short, price rises.
-                const liquidationPrice = leverage > 0
-                    ? side === 'long'
-                        ? entryPrice * (1 - 1 / leverage)
-                        : entryPrice * (1 + 1 / leverage)
-                    : 0;
-                const currentPrice = entryPrice;
-                const distanceToLiquidationPct = liquidationPrice > 0
-                    ? Math.abs((currentPrice - liquidationPrice) / currentPrice) * 100
+            const marketsByCustody = await readAdrenaMarketsByCustody(context);
+            const zones = accounts
+                .map(({ pubkey, account }) => decodeAdrenaPositionAccount(pubkey, account.data, marketsByCustody))
+                .filter((position) => Boolean(position))
+                .map((position) => {
+                const currentPrice = position.entryPrice;
+                const distanceToLiquidationPct = position.liquidationPrice > 0 && currentPrice > 0
+                    ? Math.abs((currentPrice - position.liquidationPrice) / currentPrice) * 100
                     : 0;
                 return {
-                    positionKey: pubkey.toBase58(),
-                    market: 'unknown',
-                    side,
-                    liquidationPrice,
+                    positionKey: position.positionKey,
+                    market: position.market,
+                    side: position.side,
+                    liquidationPrice: position.liquidationPrice,
                     currentPrice,
                     distanceToLiquidationPct,
-                    leverage,
+                    leverage: position.leverage,
                 };
             });
             return createTextResponse(JSON.stringify({
                 wallet: walletStr,
                 zones,
                 count: zones.length,
+                scan: {
+                    programId: getAdrenaProgramId(context).toBase58(),
+                    positionDiscriminator: discToBase58(DISC_POSITION),
+                    ownerMemcmpOffset: ADRENA_POSITION_OWNER_MEMCMP_OFFSET,
+                },
+                note: 'Liquidation zones use entryPrice as currentPrice until SAP MCP has a live Adrena oracle/feed price decoder. Treat the output as risk geometry, not a liquidation alert feed.',
             }));
         }
         catch (err) {
@@ -1120,12 +1491,214 @@ function registerPerpTradePlanTool(server) {
         }, null, 2));
     });
 }
+/* ═══════════════════════════════════════════════════════════════════
+ *  Tool 9: sap_perp_builder_status
+ * ═══════════════════════════════════════════════════════════════════ */
+function registerPerpBuilderStatusTool(server, context) {
+    const schema = {
+        type: 'object',
+        properties: {
+            venue: {
+                type: 'string',
+                description: 'Optional perp venue to check, for example "adrena" or "sap-perps-provider".',
+            },
+        },
+        additionalProperties: false,
+    };
+    registerTool(server, 'sap_perp_builder_status', {
+        description: 'Free readiness check for perps execution. Returns whether SAP MCP has a configured hosted unsigned transaction builder for perp orders. If builderAvailable is false, agents must stop before execution and must not route direct signer-only perps tools through x402 paid-call replay.',
+        inputSchema: schema,
+    }, async (args) => {
+        const perps = getPerpsConfig(context);
+        const venue = typeof args['venue'] === 'string' ? args['venue'] : 'configured-perps-provider';
+        return createTextResponse(JSON.stringify({
+            venue,
+            marketsProviderConfigured: Boolean(perps.marketsUrl),
+            positionsProviderConfigured: Boolean(perps.positionsUrl),
+            builderAvailable: Boolean(perps.builderUrl),
+            adrenaProgramId: perps.adrenaProgramId,
+            rpcScanMode: 'anchor-discriminator-getProgramAccounts',
+            scanDiscriminators: {
+                pool: discToBase58(DISC_POOL),
+                custody: discToBase58(DISC_CUSTODY),
+                position: discToBase58(DISC_POSITION),
+            },
+            builderMode: perps.builderUrl ? 'hosted_unsigned_transaction_builder' : 'not_configured',
+            nativeAdrenaDecoder: {
+                available: true,
+                source: 'official Adrena release/39 ABI layout',
+                sdkPackage: 'adrena-sdk@beta (types only, no runtime JS — using vendored IDL with @coral-xyz/anchor instead)',
+            },
+            nativeAdrenaBuilder: {
+                available: true,
+                source: 'vendored Adrena IDL (release/39) + @coral-xyz/anchor',
+                operations: [
+                    'sap_adrena_build_open_long',
+                    'sap_adrena_build_open_short',
+                    'sap_adrena_build_close_long',
+                    'sap_adrena_build_close_short',
+                    'sap_adrena_build_set_stop_loss',
+                    'sap_adrena_build_set_take_profit',
+                    'sap_adrena_build_cancel_stop_loss',
+                    'sap_adrena_build_cancel_take_profit',
+                    'sap_adrena_build_add_limit_order',
+                    'sap_adrena_build_cancel_limit_order',
+                    'sap_adrena_build_open_commodity_long',
+                    'sap_adrena_build_open_commodity_short',
+                    'sap_adrena_build_close_commodity_long',
+                    'sap_adrena_build_close_commodity_short',
+                    'sap_adrena_build_add_liquidity',
+                    'sap_adrena_build_remove_liquidity',
+                    'sap_adrena_build_swap',
+                    'sap_adrena_build_init_user_staking',
+                    'sap_adrena_build_add_liquid_stake',
+                    'sap_adrena_build_remove_liquid_stake',
+                    'sap_adrena_build_add_locked_stake',
+                    'sap_adrena_build_claim_stakes',
+                ],
+                dataApi: [
+                    'sap_adrena_get_positions',
+                    'sap_adrena_get_pool_info',
+                    'sap_adrena_get_custody_info',
+                    'sap_adrena_get_trader_info',
+                    'sap_adrena_get_trader_leaderboard',
+                    'sap_adrena_get_mutagen',
+                    'sap_adrena_get_mutagen_leaderboard',
+                    'sap_adrena_get_prices',
+                    'sap_adrena_get_trading_prices',
+                    'sap_adrena_get_position_status',
+                ],
+                signerPolicy: 'All builder tools return unsigned base64 transactions. Sign locally via sap_payments_finalize_transaction. SAP MCP never signs user-owned Adrena transactions.',
+            },
+            signerPolicy: 'Use sap_adrena_build_* tools to construct unsigned transactions, then sign locally with sap_payments_finalize_transaction.',
+            paymentPolicy: perps.builderUrl
+                ? 'Calling sap_perp_build_order_transaction is a paid builder call; finalization happens locally without exposing keypair bytes.'
+                : 'No x402 payment is required to learn that perps execution is unavailable.',
+            nextAction: perps.builderUrl
+                ? 'Use sap_perp_trade_plan, then sap_perp_build_order_transaction, then sap_payments_finalize_transaction with submit:true after user confirmation.'
+                : 'Use sap_perp_trade_plan and chart tools for analysis only. Configure SAP_MCP_PERPS_BUILDER_URL only when the provider returns complete unsigned Solana transactions for local finalization.',
+        }, null, 2));
+    });
+}
+/* ═══════════════════════════════════════════════════════════════════
+ *  Optional Tool 10: sap_perp_build_order_transaction
+ * ═══════════════════════════════════════════════════════════════════ */
+function registerPerpOrderBuilderTool(server, context) {
+    const perps = getPerpsConfig(context);
+    if (!perps.builderUrl) {
+        return false;
+    }
+    const schema = {
+        type: 'object',
+        properties: {
+            venue: {
+                type: 'string',
+                description: 'Perps venue supported by the configured builder, for example "adrena".',
+            },
+            owner: {
+                type: 'string',
+                description: 'User wallet public key that will sign and own the perp order/position.',
+            },
+            market: {
+                type: 'string',
+                description: 'Market symbol or provider market id, for example SOL-PERP.',
+            },
+            side: {
+                type: 'string',
+                description: 'Trade side for the order.',
+                enum: ['long', 'short'],
+            },
+            orderType: {
+                type: 'string',
+                description: 'Order type supported by the provider. Use "market" unless the provider explicitly supports limit/trigger orders.',
+                enum: ['market', 'limit', 'trigger'],
+            },
+            collateralMint: {
+                type: 'string',
+                description: 'Collateral token mint. Use USDC mint for USDC-margined perps unless the provider says otherwise.',
+            },
+            collateralAmount: {
+                type: 'string',
+                description: 'Collateral amount in smallest token units, for example micro-USDC for USDC.',
+            },
+            leverage: {
+                type: 'number',
+                description: 'Requested leverage multiplier after local policy checks.',
+                minimum: 1,
+                maximum: 100,
+            },
+            slippageBps: {
+                type: 'number',
+                description: 'Maximum slippage in basis points. Keep <= 100 unless user explicitly confirms higher risk.',
+                minimum: 0,
+                maximum: 10_000,
+            },
+            reduceOnly: {
+                type: 'boolean',
+                description: 'Set true only for reduce-only close/reduce flows.',
+            },
+            limitPrice: {
+                type: 'number',
+                description: 'Optional limit or trigger price in USD when orderType is limit or trigger.',
+                minimum: 0,
+            },
+            clientOrderId: {
+                type: 'string',
+                description: 'Optional client id for idempotency/audit. Generate once and reuse on retries.',
+            },
+        },
+        required: ['owner', 'market', 'side', 'orderType', 'collateralMint', 'collateralAmount', 'leverage'],
+        additionalProperties: false,
+    };
+    registerTool(server, 'sap_perp_build_order_transaction', {
+        description: 'Build an unsigned perps order transaction using the configured hosted perps builder. This tool is registered only when SAP_MCP_PERPS_BUILDER_URL is configured. It must return an unsigned Solana transaction for local finalization; SAP MCP never signs user-owned perps transactions on hosted.',
+        inputSchema: schema,
+    }, async (args) => {
+        const payload = await timedFetch(perps.builderUrl, {
+            method: 'POST',
+            headers: perpsProviderHeaders(),
+            body: JSON.stringify({
+                ...args,
+                requestedBy: 'sap-mcp-hosted',
+                signerPolicy: 'local-finalization-required',
+            }),
+            timeoutMs: perps.timeoutMs,
+        });
+        const transactionBase64 = payload?.transactionBase64
+            ?? payload?.unsignedTransactionBase64
+            ?? payload?.transaction;
+        if (!payload || typeof transactionBase64 !== 'string' || transactionBase64.length === 0) {
+            return createTextResponse(JSON.stringify({
+                error: 'perps_builder_invalid_response',
+                message: 'Configured perps builder did not return transactionBase64/unsignedTransactionBase64. Execution stopped before local signing.',
+                expectedNextStep: 'Fix SAP_MCP_PERPS_BUILDER_URL provider response. Do not create temporary signing scripts or hand-roll perps transactions.',
+            }, null, 2), { isError: true });
+        }
+        return createTextResponse(JSON.stringify({
+            success: true,
+            venue: args['venue'] ?? 'configured-perps-provider',
+            transactionBase64,
+            lastValidBlockHeight: payload.lastValidBlockHeight,
+            blockhash: payload.blockhash,
+            feePayer: payload.feePayer,
+            provider: payload.provider ?? 'configured-perps-builder',
+            signerPolicy: 'local-finalization-required',
+            nextTool: 'sap_payments_finalize_transaction',
+            finalizeArgs: {
+                transactionBase64,
+                submit: false,
+            },
+            warnings: payload.warnings,
+        }, null, 2));
+    });
+    return true;
+}
 /* ═══════════════════════════════════════════════════════════════════
  *  Main registration function
  * ═══════════════════════════════════════════════════════════════════ */
 /**
  * @name registerPerpTools
- * @description Register all 8 perp trading analytics and planning MCP tools.
+ * @description Register perp trading analytics, planning, and optional execution-builder tools.
  *
  * @param server  — MCP server instance.
  * @param context — Shared runtime context with SAP client, connection, and config.
@@ -1142,6 +1715,8 @@ export function registerPerpTools(server, context) {
     registerChartVolumeProfileTool(server, context);
     registerPerpLiquidationZonesTool(server, context);
     registerPerpTradePlanTool(server);
-    logger.debug('Perp tools registered', { count: 8 });
+    registerPerpBuilderStatusTool(server, context);
+    const builderRegistered = registerPerpOrderBuilderTool(server, context);
+    logger.debug('Perp tools registered', { count: builderRegistered ? 10 : 9, builderRegistered });
 }
 //# sourceMappingURL=perp-tools.js.map