{
  "format": "siebly-agent-recipe/v1",
  "id": "binance-usdm-algo-orders",
  "title": "Binance USD-M Algo TP/SL Orders",
  "lastReviewed": "2026-04-28",
  "package": {
    "ecosystem": "npm",
    "name": "binance",
    "install": "npm install binance",
    "docs": "https://siebly.io/sdk/binance/typescript",
    "repository": "https://github.com/tiagosiebler/binance"
  },
  "scope": {
    "runtime": "Node.js LTS",
    "language": "TypeScript",
    "product": "Binance USD-M Futures",
    "defaultMode": "source verification plus dry-run request building",
    "liveTradingDefault": false,
    "credentials": "scoped API keys from environment variables only"
  },
  "requiredSources": [
    "https://siebly.io/ai/binance-usdm-algo-orders",
    "https://siebly.io/ai/binance-position-manager",
    "https://siebly.io/sdk/binance/typescript",
    "https://siebly.io/.well-known/agent-skills/siebly-crypto-exchange-api/SKILL.md",
    "https://siebly.io/llms.txt",
    "https://siebly.io/llms-tasks.txt",
    "https://siebly.io/llms-full.txt",
    "https://siebly.io/.well-known/siebly-sdk-catalog.json",
    "https://github.com/tiagosiebler/binance"
  ],
  "sdkSurfacesToVerify": {
    "restClient": "USDMClient",
    "algoMethods": [
      "submitNewAlgoOrder",
      "getOpenAlgoOrders",
      "cancelAlgoOrder"
    ],
    "requestTypes": [
      "FuturesNewAlgoOrderParams",
      "FuturesAlgoConditionalOrderTypes",
      "FuturesAlgoOrderResponse"
    ],
    "userDataTypes": [
      "WsMessageFuturesUserDataAlgoUpdateFormatted",
      "WsMessageFuturesUserDataTradeUpdateEventFormatted",
      "WsUserDataEvents"
    ],
    "clientOrderId": [
      "clientAlgoId",
      "getOrderIdPrefix(...)",
      "generateNewOrderId(...)"
    ]
  },
  "validExamples": {
    "takeProfitLimit": "await usdm.submitNewAlgoOrder({\n  algoType: 'CONDITIONAL',\n  symbol,\n  side: exitSide,\n  positionSide,\n  type: 'TAKE_PROFIT',\n  timeInForce: 'GTC',\n  quantity,\n  price: takeProfitPrice,\n  triggerPrice: takeProfitTriggerPrice,\n  workingType: 'MARK_PRICE',\n  priceProtect: 'true',\n  reduceOnly: 'true',\n  clientAlgoId,\n});",
    "closePositionStopMarket": "await usdm.submitNewAlgoOrder({\n  algoType: 'CONDITIONAL',\n  symbol,\n  side: exitSide,\n  positionSide,\n  type: 'STOP_MARKET',\n  triggerPrice: stopTriggerPrice,\n  workingType: 'MARK_PRICE',\n  priceProtect: 'true',\n  closePosition: 'true',\n  clientAlgoId,\n});"
  },
  "invalidExamples": {
    "invalidTypeAndClosePositionCombination": "// Invalid for the current USD-M Algo Service:\ntype: 'TAKE_PROFIT_LIMIT'\n\n// Invalid close-position combination:\n{\n  closePosition: 'true',\n  quantity,\n  reduceOnly: 'true',\n}"
  },
  "validationRules": [
    "Use algoType=CONDITIONAL for current USD-M Algo conditional TP/SL requests.",
    "Use type=TAKE_PROFIT for a limit take-profit. Do not use strategy-language names such as TAKE_PROFIT_LIMIT unless current package types and Binance docs explicitly support them.",
    "Use type=STOP_MARKET with closePosition=true for a close-position stop-market conditional.",
    "When closePosition=true, omit quantity and reduceOnly unless current Binance docs and package types say otherwise.",
    "When using a quantity-based reduce-only TP, include quantity and reduceOnly=true, then validate quantity, tick size, step size, and notional before submission.",
    "Use clientAlgoId for USD-M Algo conditionals, not newClientOrderId. It is still a Binance custom client order ID and must pass the same SDK prefix, length, and character checks as other custom order ID fields.",
    "Keep request builders strict: omit undefined optional fields instead of sending them as undefined."
  ],
  "userDataRules": [
    "Hydrate open Algo orders over REST before planning.",
    "Reconcile Algo updates from typed user-data fields such as eventType, symbol, positionSide, clientAlgoId, order status, and execution type.",
    "Choose formattedUserDataMessage or formattedMessage for private state processing; do not process both without dedupe.",
    "Redact user-data wsKey values because they may contain listen-key-like material."
  ],
  "fixtureCases": [
    {
      "name": "Valid reduce-only take-profit",
      "expected": "Request uses TAKE_PROFIT, quantity, price, triggerPrice, reduceOnly=true, and clientAlgoId."
    },
    {
      "name": "Valid close-position stop-market",
      "expected": "Request uses STOP_MARKET, triggerPrice, closePosition=true, and omits quantity and reduceOnly."
    },
    {
      "name": "Invalid strategy-language take-profit type",
      "expected": "Local validation rejects TAKE_PROFIT_LIMIT before Binance can return an invalid order type error."
    },
    {
      "name": "Invalid close-position field mix",
      "expected": "Local validation rejects closePosition=true with quantity or reduceOnly."
    },
    {
      "name": "Open Algo hydration",
      "expected": "Existing app-owned TP/SL Algo orders block duplicate replacement unless replacement is required."
    },
    {
      "name": "Algo user-data update",
      "expected": "A formatted Algo update reconciles the matching app-owned order from typed fields."
    }
  ],
  "knownRejections": [
    {
      "code": "-1116",
      "message": "Invalid orderType",
      "fix": "Verify the current Algo type enum and use TAKE_PROFIT for a limit take-profit when that is the supported value."
    },
    {
      "code": "-1106",
      "message": "Parameter 'reduceonly' sent when not required",
      "fix": "For closePosition=true stop-market conditionals, omit reduceOnly and quantity."
    },
    {
      "code": "-4116",
      "message": "ClientOrderId is duplicated",
      "fix": "Track in-flight clientAlgoId values and reconcile open Algo orders before retrying."
    },
    {
      "code": "-1111",
      "message": "Precision is over the maximum defined for this asset",
      "fix": "Use hydrated symbol filters to round and validate price, quantity, and notional before building the request."
    }
  ],
  "safety": [
    "Build and test request objects in dry-run mode before enabling live submission.",
    "Live trading must require explicit user configuration, scoped credentials, and reviewed code.",
    "A rejected live request should pause the affected product scope and force reconciliation before retry.",
    "This recipe is not a replacement for Binance API docs or the installed package types."
  ]
}