{
  "format": "siebly-conformance-pack/v1",
  "id": "binance-position-manager",
  "title": "Binance Manual Position Manager Conformance Pack",
  "lastReviewed": "2026-04-30",
  "package": {
    "ecosystem": "npm",
    "name": "binance",
    "install": "npm install binance",
    "versionPolicy": "Use the latest available binance package in the generated project. Record the installed version for source verification only; do not pin implementation guidance to a feedback-run package version."
  },
  "canonicalArtifacts": {
    "manifest": "https://siebly.io/.well-known/agent-manifests/binance-position-manager/latest.json",
    "integrationKit": "https://siebly.io/.well-known/integration-kits/binance-position-manager/latest.json",
    "recipe": "https://siebly.io/.well-known/recipes/binance-position-manager.json",
    "guide": "https://siebly.io/ai/binance-position-manager",
    "usdmAlgoRecipe": "https://siebly.io/.well-known/recipes/binance-usdm-algo-orders.json"
  },
  "schema": {
    "fixture": {
      "name": "string",
      "product": "spot | usdm | multi",
      "given": "hydration snapshots, buffered events, in-memory state, intents, or errors",
      "expect": "planner outputs, submit calls, state transitions, log markers, active counts, and blocked actions"
    },
    "trace": {
      "event": "log event name",
      "requiredFields": "fields or matchers that must be present"
    }
  },
  "criticalLiveConformance": {
    "mustPassBeforeLive": [
      "manual_open_reacts_without_timer",
      "accepted_submissions_settle_to_zero_intents",
      "usdm_algo_close_position_hydration_defaults",
      "manual_same_side_add_replaces_generation_once",
      "repeat_client_id_guard_preflights_batch",
      "live_submission_exception_clears_inflight",
      "unknown_order_cancel_absent_from_hydration_marks_terminal",
      "private_stream_exception_fails_startup",
      "deferred_replan_reentrant_calls_coalesce",
      "hedge_same_symbol_opposite_side_coexists",
      "full_close_cleanup_clears_lifecycle_after_cleanup_settles"
    ],
    "mustLogFields": [
      "event",
      "product",
      "intentCount",
      "blockedCount",
      "activeOrders",
      "positions",
      "bufferedEventCount",
      "readiness"
    ],
    "mustNeverLogRawFields": [
      "apiKey",
      "apiSecret",
      "signature",
      "listenKey",
      "wsKey",
      "signedUrl",
      "rawOrderIntent"
    ]
  },
  "fixtures": [
    {
      "name": "manual_open_reacts_without_timer",
      "product": "usdm",
      "given": {
        "initialHydration": {
          "positions": [],
          "regularOpenOrders": [],
          "openAlgoOrders": [],
          "filters": [
            {
              "symbol": "BTCUSDT",
              "tickSize": "0.1",
              "stepSize": "0.001"
            }
          ]
        },
        "events": [
          {
            "eventType": "TRADE_LITE",
            "symbol": "BTCUSDT"
          },
          {
            "eventType": "ORDER_TRADE_UPDATE",
            "symbol": "BTCUSDT",
            "positionSide": "BOTH"
          },
          {
            "eventType": "ACCOUNT_UPDATE"
          }
        ],
        "postEventHydration": {
          "positions": [
            {
              "symbol": "BTCUSDT",
              "positionSide": "BOTH",
              "positionAmt": "0.01",
              "entryPrice": "100000.0"
            }
          ],
          "regularOpenOrders": [],
          "openAlgoOrders": []
        }
      },
      "expect": {
        "scheduledDelayMs": 0,
        "firstIntentRoles": [
          "SL",
          "TP",
          "DCA"
        ],
        "noTimerWait": true
      }
    },
    {
      "name": "accepted_submissions_settle_to_zero_intents",
      "product": "usdm",
      "given": {
        "hydration": {
          "positions": [
            {
              "symbol": "BTCUSDT",
              "positionSide": "BOTH",
              "positionAmt": "0.01"
            }
          ],
          "regularOpenOrders": [
            {
              "role": "DCA",
              "clientId": "app-owned-dca"
            }
          ],
          "openAlgoOrders": [
            {
              "role": "SL",
              "clientAlgoId": "app-owned-sl"
            },
            {
              "role": "TP",
              "clientAlgoId": "app-owned-tp"
            }
          ]
        }
      },
      "expect": {
        "activeOrders": 3,
        "intentCount": 0,
        "cancelIntents": 0,
        "placeIntents": 0
      }
    },
    {
      "name": "usdm_algo_close_position_hydration_defaults",
      "description": "A deterministic app-owned USD-M Algo close-position STOP_MARKET SL can hydrate with exchange defaults that should not churn replacement.",
      "desired": {
        "product": "usdm",
        "kind": "algo",
        "role": "SL",
        "type": "STOP_MARKET",
        "closePosition": true,
        "quantity": null,
        "price": null,
        "reduceOnly": null,
        "triggerPrice": "99000.0",
        "positionSide": "BOTH"
      },
      "hydratedVariants": [
        {
          "quantity": "0.0",
          "price": "0.0",
          "closePosition": "true",
          "reduceOnly": "false",
          "priceProtect": "true"
        },
        {
          "quantity": "0.01",
          "price": "0.0",
          "closePosition": false,
          "reduceOnly": true,
          "priceProtect": true
        },
        {
          "quantity": null,
          "price": null,
          "closePosition": null,
          "reduceOnly": null,
          "priceProtect": null
        }
      ],
      "equivalenceRule": "After matching product, symbol, exchangePositionSide, managedStrategySide, role, lifecycleEpoch, replacementGeneration, side, triggerPrice, workingType, and priceProtect, ignore quantity, price, closePosition, and reduceOnly for deterministic app-owned close-position SL comparison.",
      "expect": {
        "equivalent": true,
        "intentCount": 0,
        "doNotCancel": true
      }
    },
    {
      "name": "repeat_client_id_guard_preflights_batch",
      "product": "usdm",
      "given": {
        "recentlyAcceptedClientIds": [
          "sl-l1-g0"
        ],
        "batch": [
          {
            "action": "cancel",
            "role": "SL",
            "clientId": "sl-l1-g0"
          },
          {
            "action": "place",
            "role": "SL",
            "clientId": "sl-l1-g0"
          }
        ]
      },
      "expect": {
        "preflightFailsBeforeExchangeCall": true,
        "exchangeSubmitCalls": 0,
        "pauseReason": "repeat_live_client_id_guard"
      }
    },
    {
      "name": "live_submission_exception_clears_inflight",
      "product": "usdm",
      "given": {
        "inFlightBefore": [],
        "batch": [
          {
            "action": "cancel",
            "role": "SL",
            "clientId": "sl-old"
          }
        ],
        "exchangeError": {
          "code": "-2011",
          "message": "Unknown order sent."
        }
      },
      "expect": {
        "inFlightAfter": [],
        "productPaused": true,
        "structuredErrorLogged": true
      }
    },
    {
      "name": "unknown_order_cancel_absent_from_hydration_marks_terminal",
      "product": "usdm",
      "given": {
        "openAlgoOrders": [],
        "cancelTarget": {
          "role": "SL",
          "clientAlgoId": "stale-sl"
        },
        "cancelError": {
          "code": "-2011",
          "message": "Unknown order sent."
        }
      },
      "expect": {
        "orderState": "terminal_or_stale",
        "retryCancelForever": false,
        "inFlightAfter": []
      }
    },
    {
      "name": "private_stream_exception_fails_startup",
      "product": "usdm",
      "given": {
        "events": [
          {
            "sdkEvent": "exception",
            "product": "usdm",
            "error": {
              "message": "listen key failed"
            }
          }
        ],
        "requiredPrivateProducts": [
          "usdm"
        ]
      },
      "expect": {
        "readiness": "paused",
        "serviceReadyLogged": false,
        "startupFailsBeforeLive": true,
        "nestedSdkErrorPreserved": true
      }
    },
    {
      "name": "deferred_replan_reentrant_calls_coalesce",
      "product": "usdm",
      "given": {
        "activeWorkflow": true,
        "reentrantEvents": [
          {
            "eventType": "ORDER_TRADE_UPDATE"
          },
          {
            "eventType": "ALGO_UPDATE"
          },
          {
            "eventType": "ORDER_TRADE_UPDATE"
          }
        ]
      },
      "expect": {
        "followUpOwners": 1,
        "deferredReasonsCoalesced": true,
        "logStorm": false,
        "finalIntentCount": 0
      }
    },
    {
      "name": "manual_same_side_add_replaces_generation_once",
      "product": "usdm",
      "given": {
        "existingLifecycle": {
          "side": "LONG",
          "lifecycleEpoch": "L1",
          "replacementGeneration": 0
        },
        "hydratedPosition": {
          "quantity": "0.02",
          "averageEntry": "100500.0"
        },
        "oppositeHedgeSideOpen": true
      },
      "expect": {
        "lifecycleEpoch": "L1",
        "replacementGeneration": 1,
        "submitRolesInOrder": [
          "SL",
          "TP",
          "DCA"
        ],
        "oppositeSideTouched": false,
        "convergenceIntentCount": 0
      }
    },
    {
      "name": "hedge_same_symbol_opposite_side_coexists",
      "product": "usdm",
      "given": {
        "hedgeMode": true,
        "positions": [
          {
            "symbol": "BTCUSDT",
            "positionSide": "LONG",
            "quantity": "0.01"
          },
          {
            "symbol": "BTCUSDT",
            "positionSide": "SHORT",
            "quantity": "0.01"
          }
        ],
        "existingLongOrders": 3
      },
      "expect": {
        "shortOrdersCreated": 3,
        "longOrdersCancelled": 0,
        "finalPositions": 2,
        "finalActiveOrders": 6,
        "finalIntentCount": 0
      }
    },
    {
      "name": "full_close_cleanup_clears_lifecycle_after_cleanup_settles",
      "product": "usdm",
      "given": {
        "lifecycle": {
          "lifecycleEpoch": "L1",
          "side": "LONG"
        },
        "hydrationAfterCleanup": {
          "positions": [],
          "regularOpenOrders": [],
          "openAlgoOrders": []
        }
      },
      "expect": {
        "lifecycleCleared": true,
        "nextSameSymbolSameSideLifecycle": "new",
        "replacementGeneration": 0
      }
    },
    {
      "name": "binary_float_precision_tails_are_formatted",
      "product": "usdm",
      "given": {
        "price": "74992.800000000003",
        "tickSize": "0.1",
        "quantity": "0.0020000000000000005",
        "stepSize": "0.001"
      },
      "expect": {
        "price": "74992.8",
        "quantity": "0.002",
        "submitRawFloatTail": false
      }
    },
    {
      "name": "fallback_filters_block_live_planning",
      "product": "usdm",
      "given": {
        "hydratedFiltersMissing": true,
        "liveCapableIntent": {
          "role": "DCA"
        }
      },
      "expect": {
        "blocked": true,
        "submitted": false,
        "reason": "missing_hydrated_filters"
      }
    }
  ],
  "goldenLogTraces": {
    "manualOpen": [
      {
        "event": "user_data_schedules_reconcile",
        "eventType": "ORDER_TRADE_UPDATE",
        "delayMs": 0
      },
      {
        "event": "buffered_events_replayed",
        "bufferedEventCount": {
          "gte": 1
        }
      },
      {
        "event": "planner_finished",
        "positions": 1,
        "activeOrders": 0,
        "intentCount": 3
      },
      {
        "event": "submission_batch_started",
        "intentCount": 3
      },
      {
        "event": "live_submission_accepted",
        "role": "SL",
        "action": "place"
      },
      {
        "event": "live_submission_accepted",
        "role": "TP",
        "action": "place"
      },
      {
        "event": "live_submission_accepted",
        "role": "DCA",
        "action": "place"
      },
      {
        "event": "planner_finished",
        "positions": 1,
        "activeOrders": 3,
        "intentCount": 0
      }
    ],
    "sameSideAdd": [
      {
        "event": "planner_finished",
        "positions": 1,
        "activeOrders": 3,
        "intentCount": 6
      },
      {
        "event": "live_submission_accepted",
        "role": "SL",
        "action": "cancel",
        "reason": "managed_order_generation_changed"
      },
      {
        "event": "live_submission_accepted",
        "role": "TP",
        "action": "cancel",
        "reason": "managed_order_generation_changed"
      },
      {
        "event": "live_submission_accepted",
        "role": "DCA",
        "action": "cancel",
        "reason": "managed_order_generation_changed"
      },
      {
        "event": "live_submission_accepted",
        "role": "SL",
        "action": "place"
      },
      {
        "event": "live_submission_accepted",
        "role": "TP",
        "action": "place"
      },
      {
        "event": "live_submission_accepted",
        "role": "DCA",
        "action": "place"
      },
      {
        "event": "planner_finished",
        "positions": 1,
        "activeOrders": 3,
        "intentCount": 0
      }
    ],
    "hedgeCoexistence": [
      {
        "event": "planner_finished",
        "positions": 1,
        "activeOrders": 0,
        "intentCount": 3,
        "side": "LONG"
      },
      {
        "event": "planner_finished",
        "positions": 2,
        "activeOrders": 3,
        "intentCount": 3,
        "side": "SHORT"
      },
      {
        "event": "planner_finished",
        "positions": 2,
        "activeOrders": 6,
        "intentCount": 0
      }
    ]
  },
  "snippets": {
    "privateStartup": "ws.on('exception', (event) => supervisor.onException(event));\nws.on('open', (event) => supervisor.onOpen(event));\nws.on('reconnecting', (event) => supervisor.onReconnecting(event));\nws.on('reconnected', (event) => supervisor.onReconnected(event));\n\nawait adapter.connectPrivateStreams();\n\nconst failed = products.filter((product) => store.getReadiness(product) === 'paused');\nif (failed.length > 0) {\n  throw new Error(`Private stream startup failed for products: ${failed.join(',')}`);\n}\n\nawait hydrateAllEnabledProducts();\nawait replayBufferedEvents();\nlogger.info('service_ready', { products });",
    "liveBatchPreflight": "async function submitBatchInsideWorkflow(intents) {\n  const submitIntents = intents.filter((intent) => !intent.blocked);\n  if (submitIntents.length === 0) {\n    logger.info('submission_batch_skipped_empty', { intentCount: 0 });\n    return;\n  }\n\n  const seen = new Set();\n\n  for (const intent of submitIntents) {\n    if (recentlyAccepted(intent.clientId)) {\n      throw pauseProduct('repeat_live_client_id_guard', { clientId: intent.clientId });\n    }\n    if (seen.has(intent.clientId) || inFlight.has(intent.clientId)) {\n      throw pauseProduct('duplicate_or_inflight_client_id', { clientId: intent.clientId });\n    }\n    seen.add(intent.clientId);\n  }\n\n  for (const intent of submitIntents) {\n    inFlight.add(intent.clientId);\n    try {\n      const response = await exchange.submit(intent);\n      markRecentlyAccepted(intent.clientId);\n      if (intent.action === 'place') {\n        store.insertProvisionalAppOwnedOrder(intent, response);\n      }\n    } catch (error) {\n      pauseProduct('live_submission_exception', serializeSdkError(error));\n      throw error;\n    } finally {\n      inFlight.delete(intent.clientId);\n    }\n  }\n}",
    "orderComparison": "function ordersEquivalent(desired, active, filters) {\n  const ignored = new Set();\n\n  if (isUsdmAlgoClosePositionStopLoss(desired, active)) {\n    ignored.add('quantity');\n    ignored.add('price');\n    ignored.add('closePosition');\n    ignored.add('reduceOnly');\n  }\n\n  if (isUsdmHedgeAlgoExit(desired)) {\n    ignored.add('reduceOnly');\n  }\n\n  return compareFields([\n    ['product', desired.product, active.product],\n    ['symbol', desired.symbol, active.symbol],\n    ['exchangePositionSide', desired.exchangePositionSide, active.exchangePositionSide],\n    ['managedStrategySide', desired.managedStrategySide, active.managedStrategySide],\n    ['role', desired.role, active.role],\n    ['step', desired.step, active.step],\n    ['lifecycleEpoch', desired.lifecycleEpoch, active.lifecycleEpoch],\n    ['replacementGeneration', desired.replacementGeneration, active.replacementGeneration],\n    ['kind', desired.kind, active.kind],\n    ['side', desired.side, active.side],\n    ['quantity', formatQty(desired.quantity, filters), formatQty(active.quantity, filters)],\n    ['price', formatPrice(desired.price, filters), formatPrice(active.price, filters)],\n    ['triggerPrice', formatPrice(desired.triggerPrice, filters), formatPrice(active.triggerPrice, filters)],\n    ['closePosition', boolLike(desired.closePosition), boolLike(active.closePosition)],\n    ['reduceOnly', boolLike(desired.reduceOnly), boolLike(active.reduceOnly)],\n    ['workingType', desired.workingType ?? '', active.workingType ?? ''],\n    ['priceProtect', boolLike(desired.priceProtect), boolLike(active.priceProtect)],\n  ], ignored);\n}",
    "structuredLogger": "function emit(level, eventName, context = {}) {\n  const { event: contextEvent, level: _level, ts: _ts, ...safeContext } = redact(context);\n  const line = {\n    ts: new Date().toISOString(),\n    level,\n    event: eventName,\n    ...safeContext,\n    ...(contextEvent === undefined ? {} : { contextEvent }),\n  };\n  console[level === 'error' ? 'error' : 'log'](JSON.stringify(line));\n}\n\nfunction serializeSdkError(error) {\n  const out = { errorType: typeof error };\n  if (error instanceof Error) {\n    out.name = error.name;\n    out.message = error.message;\n    out.stack = error.stack;\n  }\n  if (error && typeof error === 'object') {\n    out.exchangeCode = error.code;\n    out.exchangeMessage = error.msg;\n    out.message = error.message ?? out.message;\n    if (error.response) {\n      out.httpStatus = error.response.status;\n      out.responseHeaders = error.response.headers;\n      out.responseBody = error.response.data;\n    }\n    if (error.error || error.exception) {\n      out.nested = serializeSdkError(error.error ?? error.exception);\n    }\n  }\n  return redact(out);\n}"
  }
}