{ "format": "siebly-agent-recipe/v1", "id": "position-manager-core", "title": "Manual Position Manager Core Pattern", "lastReviewed": "2026-05-01", "package": { "ecosystem": "npm", "name": "selected exchange SDK", "install": "Install the maintained SDK for the selected exchange", "docs": "https://siebly.io/sdk", "repository": "Use the selected SDK repository and installed package source" }, "scope": { "runtime": "Node.js LTS", "language": "TypeScript", "products": [ "Spot where account/order APIs support the workflow", "Margin where supported by the exchange", "Linear stablecoin-margined perpetuals/futures where supported by the exchange", "Inverse coin-margined contracts where supported by the exchange" ], "defaultMode": "read-only hydration plus dry-run DCA/TP/SL order intents", "liveTradingDefault": false, "credentials": "scoped API keys from environment variables only if demo/live execution is explicitly enabled" }, "requiredSources": [ "https://siebly.io/ai/position-manager", "https://siebly.io/ai", "https://siebly.io/sdk", "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" ], "workflow": [ "Start in read-only hydration plus dry-run order-intent mode.", "Load configuration, product scope, credentials, dry-run/demo/live gates, and per-symbol DCA/TP/SL settings.", "Hydrate exchange filters, positions, open orders, recent orders, fills or executions, wallet or margin state, account mode, position mode where applicable, and risk constraints before planning.", "Store hydrated filters by product and symbol, then format final request price and quantity strings from those filters.", "Treat startup and reconnect hydration as replacement snapshots for current positions and current open orders.", "Classify app-owned orders by deterministic exchange-supported client order identifiers plus persisted lifecycle metadata.", "Detect manual positions by product, symbol, exchange position identity, managed side, size, average entry, account mode, and lifecycle epoch.", "Plan stale app-owned cleanup before new current-lifecycle placement.", "Plan protective SL and TP before exposure-increasing DCA for new managed positions.", "Default DCA to one pending next step at a time; require explicit operator opt-in for full resting ladders.", "Run reconciliation, buffered event replay, planning, and submission through a per-product owner workflow.", "When events arrive while the workflow is active, record bounded follow-up reasons and let the owner schedule one deferred reconciliation pass.", "Preflight the whole demo/live batch for duplicate, in-flight, and recently accepted deterministic client order IDs before the first exchange call.", "On accepted place responses, insert provisional app-owned order state immediately and clear accepted IDs from the in-flight set.", "On rejection, thrown error, unknown submission state, reconnect, restart, or conflicting state, pause the affected product and reconcile before submitting anything else.", "After full close or position flip, clean up only app-owned orders for that lifecycle and clear lifecycle state only after hydration proves no matching position and no active app-owned orders remain." ], "promptRequirements": [ "Store the exact generated prompt and a machine-readable prompt manifest before implementation, for example docs/AI_PROMPT.md and docs/AI_PROMPT_MANIFEST.json with createdFrom, generatedAt, exchange, product scope, selected features, permission boundary, linked artifacts, installed package versions after install, live gate names, and critical fixture names.", "For position management, treat REST API hydration as the startup and reconnect source of truth, then use private WebSocket account/order/execution/position events as the live update stream. Startup and reconnect hydration for positions and open orders should replace the current product snapshot, not only upsert rows. Do not act on a detected position until REST API state, private stream readiness, instrument filters, and account mode are all known.", "Assume the initial position can be opened manually outside the system. Detect positions by symbol, product, exchange position identity, managed strategy side, size, and lifecycle epoch, then manage only orders owned by this app unless the user explicitly configures manual-order takeover. Use deterministic exchange-supported client order identifiers to tag DCA, TP, SL, amend, cancel, and replacement actions.", "Model configurable DCA, TP, and SL rules per symbol: DCA trigger distances, maximum DCA steps, max added quantity or notional, cooldowns, TP target or ladder, SL distance, optional trailing behavior, reduce-only behavior, and whether TP/SL levels recalculate from weighted average entry after each DCA fill or manual same-side position add.", "Default DCA behavior should be one pending next step at a time. Full resting DCA ladders are a separate explicit opt-in mode, not the generated default.", "For a newly detected managed position with no app-owned orders, place protective exits before exposure-increasing DCA: stale app-owned cleanup first, then SL, then TP, then DCA.", "Treat DCA/TP/SL as app-owned lifecycle state. After a managed DCA fill or manual same-side position add, cancel or replace app-owned orders whose desired quantity, price, trigger, or exit fields changed when weighted-average recalculation is enabled. After full position close or position flip, cancel any remaining app-owned DCA/TP/SL orders without touching unowned manual orders.", "If app-owned DCA/TP/SL orders are manually cancelled while the position remains open and the product is not explicitly paused, reconciliation should recreate the missing managed orders. Accepted live submissions that remain provisional but absent from later open-order hydration should become stale after a configured grace window.", "If the local state layer marks a product untrusted, sync_required, or not ready to trade, block planning and live submission, satisfy the requested state with scoped REST hydration, and then schedule a normal reconciliation pass.", "For derivatives or margin products, verify product-specific position mode, side representation, leverage, liquidation distance, reduce-only behavior, close-all or close-on-trigger behavior, trigger price type, tick/lot/notional filters, and account mode from current docs and SDK types before coding." ], "acceptanceCriteria": [ "The project stores the exact generated prompt and selected prompt options in committed docs so later feedback can be tied back to the source prompt.", "The position manager hydrates positions, open orders, fills/executions, instrument filters, and account mode before planning any DCA, TP, or SL action.", "Startup and reconnect hydration replace the current product snapshot for positions and open orders, with recent history used as metadata and terminal evidence rather than the active open-order view.", "The system distinguishes app-owned managed orders from manual/unowned orders and will not cancel or amend unowned orders unless explicitly configured.", "DCA, TP, and SL updates are reconciled from private WebSocket events plus REST API recovery, and duplicate fills or reconnects do not create duplicate managed orders.", "Private account-level WebSocket health follows SDK lifecycle events or explicit heartbeat/exception signals rather than an account-event idle timer.", "Required private stream SDK exceptions prevent service_ready and live submission until the affected product is reconciled or reviewed.", "DCA defaults to one pending next step at a time unless full-ladder placement is explicitly configured.", "Manual-position lifecycle epoch is separate from DCA replacement generation, so a fresh same-symbol/same-side position does not inherit stale orders or fills.", "Full-close cleanup clears the old lifecycle only after REST hydration confirms no matching position and no active app-owned orders for that lifecycle.", "App-owned DCA/TP/SL orders are replaced or cleaned up after managed DCA fills, manual same-side adds, full position close, or position flip, and stale wrong-side cleanup runs before new placement.", "Desired app-owned orders are compared against active app-owned orders by normalized side, quantity, price, trigger, exit fields, lifecycle, generation, and order kind.", "Exchange-hydrated default fields do not cause cancel/recreate churn after managed order identity and actionable fields match.", "The golden live convergence trace passes: manual open schedules reconciliation, SL/TP/DCA are accepted provisionally, hydration confirms the expected app-owned active orders, and the next planner pass emits intentCount=0.", "Critical local fixtures pass before live-capable submission is enabled, including manual_open_reacts_without_timer, duplicate_client_id_preflight, hydrated_defaults_do_not_churn, and private_stream_exception_prevents_service_ready.", "Protective SL and TP are placed before exposure-increasing DCA for a new managed position.", "Binary float tails never reach exchange order requests; final request strings are tick/lot formatted from hydrated filters.", "Manual app-owned order cancellation while a position remains open is recovered, and stale provisional accepted orders cannot block replacement forever.", "Hydrated exchange filters are stored and used by the planner; fallback filters cannot silently drive live-capable requests after REST API hydration.", "If local account state reports sync_required or not-ready status, scoped REST hydration satisfies the request before any planner or submission pass." ], "fixtureCases": [ { "name": "manual_open_reacts_without_timer", "purpose": "Proves a private position/order/fill event schedules immediate reconciliation.", "expected": "The next plan emits protective exits and DCA intent without waiting for a periodic timer." }, { "name": "accepted_submissions_settle_to_zero_intents", "purpose": "Proves accepted app-owned DCA/TP/SL orders suppress duplicate replacement.", "expected": "Hydration confirms expected app-owned active orders and planner intentCount is 0." }, { "name": "hydrated_defaults_do_not_churn", "purpose": "Proves exchange default fields do not cause cancel/recreate loops.", "expected": "Equivalent active orders compare equal after order-kind-specific normalization." }, { "name": "duplicate_client_id_preflight", "purpose": "Proves duplicate deterministic order IDs are blocked before the first exchange call.", "expected": "The batch is rejected locally and no live/demo call is sent." }, { "name": "owner_only_deferred_replan", "purpose": "Proves active workflow events do not recursively schedule replans.", "expected": "Non-owner calls record bounded reasons and one owner follow-up pass drains them." }, { "name": "private_stream_exception_prevents_service_ready", "purpose": "Proves required private stream failures block false readiness.", "expected": "The affected product is paused and live/demo submission remains disabled." } ], "exchangeSpecificFieldsBelongIn": [ "The selected exchange position-manager guide.", "The selected exchange recipe, integration kit, agent manifest, and conformance pack when available.", "The installed SDK declarations and current exchange API docs." ], "safety": [ "This core recipe deliberately avoids exchange-specific field names.", "Exchange pages should reference this shared lifecycle instead of copying it as their source of truth.", "Live/demo execution must require explicit config, scoped credentials, exchange-rule verification, and reviewed code.", "The README and a visible project message should credit the Siebly Prompt Framework at https://siebly.io/ai." ] }