@reefclaw/openclaw-plugin 0.1.4 → 0.1.6

package/ccxt/binance-private.d.ts

@@ -1,4 +1,5 @@
 import type { CcxtOrder, CcxtBalance, CcxtPosition, CcxtTicker, ExchangeConfig } from '../types.js';
+import type { ClientOrderResolution } from '../exchange-adapter.js';
 import type { OrderBookDepth } from '../simulator/types.js';
 /** Result of API permission validation. */
 export interface PermissionCheckResult {
@@ -7,6 +8,18 @@ export interface PermissionCheckResult {
     canTrade: boolean;
     errors: string[];
 }
+/** Exact, weight-1 proof returned by Binance's per-clientAlgoId endpoint. */
+export interface BinanceAlgoOrderProof {
+    algoId: string | null;
+    clientAlgoId: string;
+    algoStatus: string;
+    symbol: string | null;
+    side: 'buy' | 'sell' | null;
+    orderType: string | null;
+    triggerPrice: number | null;
+    quantity: number | null;
+    closePosition: boolean | null;
+}
 export declare class BinancePrivateApi {
     private exchange;
     private testnet;
@@ -154,6 +167,12 @@ export declare class BinancePrivateApi {
      *  because "I was rate-limited" is just another flavour of "no answer").
      *  Ships dark in Phase 1 — no call sites yet. */
     queryAlgoOrderStatus(clientAlgoId: string): Promise<string | null>;
+    /**
+     * Fetch the full exchange shape for one exact conditional order. Unlike the
+     * broad open-algo snapshot, this endpoint is immediately usable after
+     * placement and is keyed by the stop's unique clientAlgoId.
+     */
+    queryAlgoOrderProof(clientAlgoId: string): Promise<BinanceAlgoOrderProof | null>;
     /** Fetch historical fills (trades) for a symbol via GET /fapi/v1/userTrades.
      *  Used by the REST gap-filler (rest-gap-filler.ts) to backfill any fills
      *  that landed during a WS blind window — when the user-data stream was
@@ -214,6 +233,8 @@ export declare class BinancePrivateApi {
      * after network timeouts — check if the order went through before retrying.
      */
     fetchOrderByClientId(clientOrderId: string, symbol: string): Promise<CcxtOrder | null>;
+    /** Resolve a deterministic client id without treating read failures as absence. */
+    resolveOrderByClientId(clientOrderId: string, symbol: string): Promise<ClientOrderResolution>;
     /** Cancel a real order on the exchange. Binance Futures splits orders across
      *  two endpoints — regular (`/fapi/v1/order`) and algo/conditional
      *  (`/fapi/v1/algoOrder`). Bracket SL/TP live in the algo bucket.

package/ccxt/binance-private.js

@@ -682,6 +682,68 @@ export class BinancePrivateApi {
             return null;
         }
     }
+    /**
+     * Fetch the full exchange shape for one exact conditional order. Unlike the
+     * broad open-algo snapshot, this endpoint is immediately usable after
+     * placement and is keyed by the stop's unique clientAlgoId.
+     */
+    async queryAlgoOrderProof(clientAlgoId) {
+        if (!clientAlgoId)
+            return null;
+        try {
+            assertNotBanned('queryAlgoOrder');
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const ex = this.exchange;
+            if (typeof ex.fapiPrivateGetAlgoOrder !== 'function')
+                return null;
+            const raw = await ex.fapiPrivateGetAlgoOrder({ clientAlgoId });
+            noteSuccess();
+            let row;
+            if (Array.isArray(raw)) {
+                row = raw
+                    .find((item) => String(item.clientAlgoId ?? '') === clientAlgoId);
+            }
+            else if (raw && typeof raw === 'object') {
+                const candidate = raw;
+                if (String(candidate.clientAlgoId ?? '') === clientAlgoId)
+                    row = candidate;
+            }
+            if (!row)
+                return null;
+            const algoStatus = String(row.algoStatus ?? '').trim().toUpperCase();
+            if (!algoStatus)
+                return null;
+            const sideValue = String(row.side ?? '').trim().toLowerCase();
+            const side = sideValue === 'buy' || sideValue === 'sell' ? sideValue : null;
+            const triggerPriceValue = Number(row.triggerPrice);
+            const quantityValue = Number(row.quantity);
+            const closePositionValue = row.closePosition;
+            const closePosition = closePositionValue === true
+                || String(closePositionValue).toLowerCase() === 'true'
+                ? true
+                : closePositionValue === false || String(closePositionValue).toLowerCase() === 'false'
+                    ? false
+                    : null;
+            return {
+                algoId: row.algoId == null ? null : String(row.algoId),
+                clientAlgoId,
+                algoStatus,
+                symbol: row.symbol == null ? null : String(row.symbol),
+                side,
+                orderType: row.orderType == null ? null : String(row.orderType).toUpperCase(),
+                triggerPrice: Number.isFinite(triggerPriceValue) && triggerPriceValue > 0
+                    ? triggerPriceValue
+                    : null,
+                quantity: Number.isFinite(quantityValue) && quantityValue >= 0 ? quantityValue : null,
+                closePosition,
+            };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            logger.warn(TAG, `queryAlgoOrderProof(${clientAlgoId}) → null/unknown (NOT a verdict): ${formatError(err)}`);
+            return null;
+        }
+    }
     /** Fetch historical fills (trades) for a symbol via GET /fapi/v1/userTrades.
      *  Used by the REST gap-filler (rest-gap-filler.ts) to backfill any fills
      *  that landed during a WS blind window — when the user-data stream was
@@ -831,6 +893,9 @@ export class BinancePrivateApi {
             timestamp: raw.timestamp ?? Date.now(),
             datetime: raw.datetime ?? new Date().toISOString(),
             timeInForce: raw.timeInForce ?? 'GTC',
+            ...(typeof raw.clientOrderId === 'string' && raw.clientOrderId.length > 0
+                ? { clientOrderId: raw.clientOrderId }
+                : {}),
         };
     }
     /** Fetch a single order by ID. Used for fill polling and idempotency checks. */
@@ -871,39 +936,84 @@ export class BinancePrivateApi {
      * after network timeouts — check if the order went through before retrying.
      */
     async fetchOrderByClientId(clientOrderId, symbol) {
+        const resolution = await this.resolveOrderByClientId(clientOrderId, symbol);
+        return resolution.status === 'found' ? resolution.order : null;
+    }
+    /** Resolve a deterministic client id without treating read failures as absence. */
+    async resolveOrderByClientId(clientOrderId, symbol) {
         try {
-            // Pre-gate: never hammer Binance during a ban. Caveat: during a ban
-            // this returns null (= "not found"), so an idempotency caller could
-            // resubmit. Accepted tradeoff — extending the IP ban for everyone is
-            // worse, and the resubmit path is itself reduce-only/bounded.
+            // Never hammer Binance during a ban. A blocked read is caught below as
+            // UNKNOWN, so it can never authorize a resubmission.
             assertNotBanned('fetchOrder');
             const raw = await this.exchange.fetchOrder(undefined, symbol, {
                 origClientOrderId: clientOrderId,
             });
             noteSuccess();
+            const canonicalSymbol = (value) => value.toUpperCase().replace(/[^A-Z0-9]/g, '').replace(/USDTUSDT$/, 'USDT');
+            const rawId = raw?.id === undefined || raw?.id === null ? '' : String(raw.id);
+            const amount = raw?.amount;
+            const filled = raw?.filled;
+            const remaining = raw?.remaining;
+            if (!raw
+                || rawId.length === 0
+                || rawId.length > 512
+                || rawId.trim() !== rawId
+                || raw.clientOrderId !== clientOrderId
+                || typeof raw.symbol !== 'string'
+                || raw.symbol.length === 0
+                || canonicalSymbol(raw.symbol) !== canonicalSymbol(symbol)
+                || (raw.side !== 'buy' && raw.side !== 'sell')
+                || (raw.type !== 'market' && raw.type !== 'limit')
+                || (raw.status !== 'open' && raw.status !== 'closed' && raw.status !== 'canceled')
+                || typeof amount !== 'number'
+                || !Number.isFinite(amount)
+                || amount <= 0
+                || typeof filled !== 'number'
+                || !Number.isFinite(filled)
+                || filled < 0
+                || filled > amount + 1e-9 * Math.max(1, amount)
+                || typeof remaining !== 'number'
+                || !Number.isFinite(remaining)
+                || remaining < 0
+                || remaining > amount + 1e-9 * Math.max(1, amount)) {
+                return { status: 'unknown', detail: 'exchange returned a malformed client-order lookup response' };
+            }
             return {
-                id: String(raw.id),
-                symbol: raw.symbol ?? symbol,
-                side: (raw.side ?? 'buy'),
-                type: (raw.type ?? 'limit'),
-                status: raw.status,
-                amount: raw.amount ?? 0,
-                filled: raw.filled ?? 0,
-                remaining: raw.remaining ?? 0,
-                average: raw.average ?? null,
-                price: raw.price ?? null,
-                cost: raw.cost ?? 0,
-                fee: raw.fee ?? { cost: 0, currency: 'USDT' },
-                timestamp: raw.timestamp ?? Date.now(),
-                datetime: raw.datetime ?? new Date().toISOString(),
-                timeInForce: raw.timeInForce ?? 'GTC',
+                status: 'found',
+                order: {
+                    id: rawId,
+                    symbol: raw.symbol,
+                    side: raw.side,
+                    type: raw.type,
+                    status: raw.status,
+                    amount,
+                    filled,
+                    remaining,
+                    average: raw.average ?? null,
+                    price: raw.price ?? null,
+                    cost: raw.cost ?? 0,
+                    fee: raw.fee ?? { cost: 0, currency: 'USDT' },
+                    timestamp: raw.timestamp ?? Date.now(),
+                    datetime: raw.datetime ?? new Date().toISOString(),
+                    timeInForce: raw.timeInForce ?? 'GTC',
+                    clientOrderId: raw.clientOrderId,
+                    ...(raw.info && typeof raw.info === 'object' ? { info: raw.info } : {}),
+                },
             };
         }
         catch (err) {
             noteBinanceError(err);
-            // Order not found is expected when checking idempotency — don't log as error
-            logger.info(TAG, `fetchOrderByClientId(${clientOrderId}) not found or failed: ${formatError(err)}`);
-            return null;
+            const candidate = err;
+            const message = formatError(err);
+            const messageCode = message.match(/"code"\s*:\s*(-?\d+)/)?.[1];
+            const directCode = typeof candidate?.code === 'number' ? candidate.code : undefined;
+            const code = directCode ?? (messageCode ? Number(messageCode) : undefined);
+            if (code === -2013) {
+                logger.info(TAG, `resolveOrderByClientId(${clientOrderId}) confirmed absent (-2013)`);
+                return { status: 'confirmed_absent' };
+            }
+            logger.warn(TAG, `resolveOrderByClientId(${clientOrderId}) outcome unknown: ${message}`);
+            return { status: 'unknown', detail: message };
         }
     }
     /** Cancel a real order on the exchange. Binance Futures splits orders across

package/config/plugin-config-io.d.ts

@@ -40,6 +40,12 @@ export interface PluginConfigFile {
      *  carry `venue` through or it resets to the binance default. */
     exchange?: ExchangeConfig;
     tradingMode?: TradingMode;
+    /** Hyperliquid-specific knobs (Phase 3). `marketSlippagePct` bounds the IOC
+     *  "market" order — HL has no native market order, and ccxt's 5% default is far
+     *  too loose to ever rely on. Clamped to ≤2% adapter-side. */
+    hl?: {
+        marketSlippagePct?: number;
+    };
     microLive?: {
         sizeCapPercent?: number;
         maxPositionUSDT?: number;

package/config/tool-gate.js

@@ -17,6 +17,9 @@ export const UNGOVERNABLE_TOOLS = new Set([
     // Core safety floor — protecting/exiting positions and the review capture.
     'create_order',
     'close_position',
+    // Reversal capabilities for existing Wave 9 positions come only from this
+    // status path, so central tool preferences must never disable it.
+    'get_wave9_status',
     'modify_stop',
     'attach_brackets',
     'audit_bracket_protection',

package/exchange-adapter.d.ts

@@ -1,5 +1,15 @@
 import type { CcxtOrder, CcxtBalance, CcxtPosition, TradingMode } from './types.js';
 import type { PositionMetadata, CloseReason } from './simulator/types.js';
+/** Deterministic client-order lookup used after an outcome-ambiguous submit. */
+export type ClientOrderResolution = {
+    status: 'found';
+    order: CcxtOrder;
+} | {
+    status: 'confirmed_absent';
+} | {
+    status: 'unknown';
+    detail: string;
+};
 /** Adapter readiness state machine: INIT_PENDING → READY | DEGRADED | BLOCKED */
 export type AdapterReadiness = 'INIT_PENDING' | 'READY' | 'DEGRADED' | 'BLOCKED';
 /** Options for order submission. */
@@ -42,6 +52,12 @@ export interface IExchangeAdapter {
     getPositionsOrNull(symbol?: string): Promise<CcxtPosition[] | null>;
     getOpenOrders(symbol?: string): Promise<CcxtOrder[]>;
     fetchOrder(orderId: string, symbol?: string): Promise<CcxtOrder | null>;
+    /**
+     * A null-style fetch is unsafe for entry recovery because network/auth/rate
+     * failures are not proof an order was absent. Live adapters expose this
+     * tri-state resolver; paper adapters may omit it.
+     */
+    resolveOrderByClientId?(clientOrderId: string, symbol: string): Promise<ClientOrderResolution>;
     getLastPrice(symbol: string): Promise<number | null>;
     readonly readiness: AdapterReadiness;
     readonly mode: TradingMode;