NautilusTrader Docs · ภาษาไทย

Events

NautilusTrader จำลองการเปลี่ยนแปลงของ execution, position, account และเวลาในรูปของ event โดย MessageBus จะส่ง event เหล่านี้ไปยัง component ที่สนใจ และส่งต่อไปยัง handler ของ strategy ในกรณีที่รองรับ คู่มือนี้อธิบายชนิดของ event, การ dispatch และวิธีที่ order fill และการแก้ไข fill ก่อให้เกิด position event

หมวดหมู่ของ event

หมวดตัวอย่างที่มา
OrderOrderAccepted, OrderFilled, OrderCanceledExecution pipeline
PositionPositionOpened, PositionAdjustedfill และการเปลี่ยนแปลงทางบัญชี
AccountAccountStateExecutionClient / Portfolio
TimeTimeEventClock (timer และ alert)

การ dispatch ไปยัง handler

เมื่อ event มาถึง strategy ระบบจะเรียก handler ตามลำดับที่ตายตัว โดย handler เฉพาะ จะทำงานก่อน handler รวม ดังนั้นจะจัดการ event ที่ระดับความละเอียดใดก็ได้ หรือใช้ทั้งสองแบบร่วมกัน

strategy จะส่ง event ไปยัง handler ของตน เฉพาะตอนที่กำลังทำงานอยู่เท่านั้น event ที่มาถึงก่อน start หรือหลัง stop จะไม่ถูก dispatch

Order event

  1. handler เฉพาะ (เช่น on_order_filled)
  2. on_order_event (รับ order event ทุกชนิด)

Position event

สำหรับ position lifecycle event ที่ dispatch ไปยัง strategy:

  1. handler เฉพาะ (เช่น on_position_opened)
  2. on_position_event (รับ position lifecycle event ทุกตัวที่ถูก dispatch)

Time event

timer และ alert จะสร้าง object TimeEvent ส่ง callback ตอนเรียก set_timer หรือ set_time_alert เพื่อส่ง event ไปยัง method ของคุณเอง

หากไม่ได้ระบุ callback:

  • จะใช้ callback ที่เคยลงทะเบียนไว้ภายใต้ชื่อเดียวกัน หากมี
  • หากไม่มี event จะถูกส่งไปที่ on_time_event

Order event

order event ใช้สร้าง order, เปลี่ยนสถานะ หรือแก้ไขประวัติ fill ของ order โดย execution pipeline จะนำ event ไปใช้กับ order และ cache แล้ว publish บน MessageBus ตารางด้านล่างแสดง transition หลัก order ที่ partially filled, order จากภายนอก และ order ที่ถูก trigger ยังรองรับ transition เพิ่มเติม ซึ่งอธิบายไว้ในลำดับสถานะของ order ฉบับเต็ม

EventTransition หลักHandler
OrderInitializedสร้างหรือ materialize orderon_order_initialized
OrderDeniedInitialized -> Deniedon_order_denied
OrderEmulatedInitialized -> Emulatedon_order_emulated
OrderReleasedEmulated -> Releasedon_order_released
OrderSubmittedInitialized/Released -> Submittedon_order_submitted
OrderAcceptedSubmitted -> Acceptedon_order_accepted
OrderRejectedSubmitted -> Rejectedon_order_rejected
OrderTriggeredAccepted -> Triggeredon_order_triggered
OrderPendingUpdateAccepted -> PendingUpdateon_order_pending_update
OrderPendingCancelAccepted -> PendingCancelon_order_pending_cancel
OrderUpdatedPendingUpdate -> สถานะก่อนหน้าon_order_updated
OrderModifyRejectedPendingUpdate -> สถานะก่อนหน้าon_order_modify_rejected
OrderCancelRejectedPendingCancel -> สถานะก่อนหน้าon_order_cancel_rejected
OrderCanceledPendingCancel/Accepted -> Canceledon_order_canceled
OrderExpiredAccepted -> Expiredon_order_expired
OrderFilledAccepted -> Filled/PartiallyFilledon_order_filled
OrderFillVoidedแก้ไข fill ที่รู้จัก หรือยืนยันสถานะ terminal สำหรับ fill ที่ไม่รู้จักon_order_fill_voided

ฟิลด์ร่วมของ order event

order event แต่ละชนิดมีฟิลด์เหล่านี้:

ฟิลด์คำอธิบาย
trader_idตัวระบุของ trader instance
strategy_idstrategy ที่เกี่ยวข้องกับ order
instrument_idinstrument ของ order
client_order_idตัวระบุ order ที่ฝั่ง client กำหนด
event_idตัวระบุ event ที่ไม่ซ้ำกัน
ts_eventUNIX timestamp (นาโนวินาที) ที่ event เกิดขึ้น
ts_initUNIX timestamp (นาโนวินาที) ที่ event ถูกสร้าง
causation_idevent หรือ report ต้นทางที่ทำให้เกิด event นี้ หากทราบ

หน้าของ order event แต่ละตัวจะระบุฟิลด์เฉพาะของชนิดนั้น ซึ่งรวมถึง venue_order_id, account_id และ reconciliation เฉพาะใน event ที่มีฟิลด์เหล่านี้ ตัวอย่างเช่น OrderFilled เพิ่ม last_qty, last_px, trade_id และ commission ส่วน OrderFillVoided ระบุ trade ที่ถูกแก้ไขและเก็บปริมาณที่ถูก void สะสมไว้

Position event

position lifecycle event อธิบายการเปลี่ยนแปลงของ position ใน cache ที่เกิดจาก fill และการแก้ไข fill ExecutionEngine จะประมวลผล OrderFilled แต่ละตัว อัปเดตหรือสร้าง position แล้ว emit lifecycle event ที่สอดคล้องกัน

เมื่อ OrderFillVoided แก้ไข fill ที่ถูกนำไปใช้ในเครื่องแล้ว จะสร้าง position ใน cache ที่ได้รับผลกระทบ ขึ้นใหม่จากประวัติ fill ที่มีผลจริง โดยไม่ emit fill ฝั่งตรงข้าม หลัง publish การแก้ไขแล้ว engine จะ emit PositionChanged สำหรับ position ที่ถูกแก้ไขและยังเปิดอยู่ หรือ PositionClosed สำหรับ position ที่ปิดแล้ว การแก้ไขที่กระทบเฉพาะ order จะไม่ทำให้เกิด position event

Eventเกิดขึ้นเมื่อHandler
PositionOpenedfill สร้าง position ใหม่on_position_opened
PositionChangedfill หรือการแก้ไขเปลี่ยน position ที่เปิดอยู่on_position_changed
PositionClosedfill หรือการแก้ไขทำให้ปริมาณเหลือศูนย์on_position_closed

PositionAdjusted ไม่เคยไปถึง position handler

PositionAdjusted บันทึกการเปลี่ยนแปลงปริมาณหรือ realized PnL ที่เกิดนอก fill ปกติ เช่น commission ที่เป็น base currency และ funding โดย ExecutionEngine จะ publish event นี้ แต่ทั้ง on_position_event และ handler เฉพาะใดๆ จะไม่ได้รับ ให้ตรวจดูประวัติที่บันทึกไว้ จาก position.adjustments()

จาก fill สู่ position: ห่วงโซ่เหตุและผล

แผนภาพต่อไปนี้แสดงว่า OrderFilled เพียงตัวเดียวก่อให้เกิด position event อย่างไร ซึ่งเป็นจุดเชื่อม ระหว่างการจัดการ order กับการติดตาม position

sequenceDiagram
    participant Venue as Venue
    participant EE as ExecutionEngine
    participant Cache as Cache
    participant Strategy as Strategy

    Venue-->>EE: OrderFilled
    EE->>EE: apply fill to order
    EE->>Cache: update order state
    EE->>EE: determine position ID

    alt No existing position
        EE->>Cache: add new Position
        EE->>Strategy: PositionOpened
    else Position open, not closed by fill
        EE->>Cache: update Position
        EE->>Strategy: PositionChanged
    else Fill closes the position
        EE->>Cache: update Position
        EE->>Strategy: PositionClosed
    end

ทีละขั้นตอน:

  1. fill มาถึง: ExecutionEngine ได้รับ event OrderFilled ผ่าน execution pipeline
  2. สถานะ order: engine นำ fill ไปใช้กับ object ของ order และเขียน order ที่อัปเดตแล้วลง Cache
  3. Position ID: engine ระบุว่า fill นี้เป็นของ position ใด โดยอิงจาก OMS type และการตั้งค่าของ strategy
  4. วงจรชีวิตของ position: engine สร้างหรืออัปเดต position ด้วยวิธีใดวิธีหนึ่งในสามแบบ:
    • ยังไม่มี position สำหรับ ID นี้: engine สร้าง Position จาก fill เพิ่มลงใน Cache และ emit PositionOpened
    • มี position อยู่และยังเปิดอยู่ หลัง fill: engine นำ fill ไปใช้กับ position อัปเดต Cache และ emit PositionChanged
    • มี position อยู่และถูกปิด (ปริมาณเหลือศูนย์): engine นำ fill ไปใช้ อัปเดต Cache และ emit PositionClosed
  5. การกลับทิศ position: เมื่อ fill ทำให้ position กลับทิศ (เช่น ขาย 15 ขณะถือ long 10) engine จะแบ่ง fill ออกเป็นสองส่วน ส่วนหนึ่งปิด position เดิม (PositionClosed) อีกส่วนเปิด position ใหม่ (PositionOpened)

ฟิลด์ของ position event

position lifecycle event ทั้งสามชนิดมีชุดฟิลด์หลักร่วมกัน และมีฟิลด์เพิ่มเติมเมื่อ position พัฒนาไป เครื่องหมายถูกหมายถึง event ชนิดนั้นมีฟิลด์นี้ ขีดหมายถึงไม่มีฟิลด์นี้

ฟิลด์OpenedChangedClosedคำอธิบาย
trader_id✓✓✓ตัวระบุของ trader instance
strategy_id✓✓✓strategy ที่เป็นเจ้าของ position
instrument_id✓✓✓instrument ของ position
position_id✓✓✓ตัวระบุ position ที่ไม่ซ้ำกัน
account_id✓✓✓account ที่ position สังกัด
opening_order_id✓✓✓order ที่เปิด position
closing_order_id--✓order ที่ปิด position
entry✓✓✓ฝั่งของ fill ที่เปิด position
side✓✓✓ฝั่งปัจจุบันของ position
signed_qty✓✓✓ปริมาณแบบมีเครื่องหมาย (ค่าลบ=short)
quantity✓✓✓ปริมาณของ position แบบไม่มีเครื่องหมาย
peak_quantity-✓✓ปริมาณสูงสุดที่เคยถือ
peak_qty-✓✓alias เพื่อความเข้ากันได้ของ peak_quantity
last_qty✓✓✓ปริมาณของ fill หรือการแก้ไข
last_px✓✓✓ราคาของ fill หรือการแก้ไข
currency✓✓✓quote currency ของ position
avg_px_open✓✓✓ราคาเข้าเฉลี่ย
avg_px_close-✓✓ราคาออกเฉลี่ย หากมี
realized_return-✓✓ผลตอบแทนที่รับรู้แล้วในรูปอัตราส่วน
realized_pnl✓✓✓realized PnL ของรอบปัจจุบันในสกุลเงินต้นทุน
unrealized_pnl-✓✓engine ตั้งค่าเป็นศูนย์
duration--✓ระยะเวลาที่ถือ หน่วยนาโนวินาที
ts_opened-✓✓timestamp ที่ position เปิด
ts_closed--✓timestamp ที่ position ปิด
event_id✓✓✓ตัวระบุ event ที่ไม่ซ้ำกัน
ts_event✓✓✓timestamp ของ event ที่เป็นตัวกระตุ้น
ts_init✓✓✓timestamp ที่ event ถูกสร้าง

การไล่ตามจาก order ไปยัง position

Cache มี method สำหรับไล่ไปมาระหว่าง order และ position ได้ทั้งจาก position ไปหา order ทุกตัวที่มี fill ร่วม และจาก order ไปหา position ที่ order นั้นสังกัด ส่วน order ที่เปิด position จะถูกเก็บไว้บน position โดยตรง

หมายเหตุ: ต้นฉบับมีเฉพาะตัวอย่าง Python จึงตัดออก

Account event

event AccountState แทน snapshot ของ balance และ margin โดยจะเกิดขึ้นเมื่อ:

  • venue รายงานการอัปเดต account (ผ่าน execution client)
  • Portfolio คำนวณสถานะ account ใหม่หลังการอัปเดต position (สำหรับ margin account ที่เปิด calculate_account_state)

account state ประกอบด้วย balance, margin, account type และ base currency โดย Portfolio จะ subscribe event เหล่านี้ภายในเพื่อติดตาม exposure และ balance ดูรายการฟิลด์ทั้งหมดได้ที่ AccountState

  • Orders - ชนิดของ order และ state machine
  • Positions - วงจรชีวิตของ position และ PnL
  • Execution - ลำดับการ execute และการตรวจสอบความเสี่ยง
  • Strategies - การ implement handler ใน strategy
  • Architecture - รูปแบบการไหลของข้อมูลและ execution

แปลจาก เอกสาร NautilusTrader © Nautech Systems Pty Ltd และผู้ร่วมพัฒนา เผยแพร่ภายใต้ LGPL-3.0 ฉบับแปลนี้ตัดเนื้อหาเฉพาะ Python ออกและเน้น Rust