Trade Strategy

This document provides the technical specification for webhooks triggered by the zerohash Trade Strategy product lifecycle. Platforms must implement these webhooks to track asynchronous operations, individual market executions, and participant account statuses.

Technical Context & Flow

Trade Strategy operations are asynchronous. Rather than polling Zero Hash APIs for status updates, platforms must listen for three distinct webhook events to manage internal state transitions.

The Lifecycle Hierarchy

1. Operation trade_strategy.operation.status_changed)
   1. The top-level parent event. It tracks the global state of a strategy intent enrollment, top_up, or partial_sell). This event fires on every state transition from initial validation to final settlement or failure.
2. Execution trade_strategy.execution.status_changed)
   1. Triggered by the operation. This tracks the market-level instructions (buys/sells) for a single participant within that parent operation. It exposes explicit fill details price, quantity, total_notional) upon settlement.
3. Trader trade_strategy.trader.created)
   1. Triggered only upon a successful enrollment operation. This fires exactly once to confirm that the participant's dedicated ledger account is active and indicates whether auto-rebalancing is enabled.

Integration Requirements

1. Payload Identification

Check the HTTP header on every incoming request to determine the payload type to process:

• Header: x-zh-hook-payload-type
• Expected Values:
  • trade_strategy.operation.status_changed
  • trade_strategy.execution.status_changed
  • trade_strategy.trader.created

2. Security & Verification

To protect against spoofing and tampering, you must verify the request signature before processing the payload. Refer to the implementation guidelines in Webhook Security.

3. Subscription Granularity

Each webhook type can be opted in independently. For complete end-to-end sync, subscribing to all three types is highly recommended.

Reference Sections

Review the sections below for explicit parameter mappings, status code dictionaries, failure reasons, and structural JSON payload examples:

• Operation Event Reference
• Execution Event Reference
• Trader Event Reference