Zero Hash Trade Strategy API

openapi: 3.2.0
info:
  title: zerohash Trade Strategy API
  description: '

    ### Authentication


    zerohash Uses HMAC SHA-256 verification to ensure the authenticity of API requests, follow instructions by link [https://docs.zerohash.com/reference/api-authentication](https://docs.zerohash.com/reference/api-authentication)


    <a href="/zh-swagger.json">Download zerohash OpenAPI Schema as JSON</a>

    '
  version: 1.7.0
servers:
- url: https://api.cert.zerohash.com
  description: Certification API server
security:
- apiKey: []
  apiPassphrase: []
tags:
- name: Trade Strategy
paths:
  /strategies:
    post:
      tags:
      - Trade Strategy
      summary: Create a Strategy
      description: Creates a new Strategy under your platform. Synchronous. The `request_id` sent as the `X-REQUEST-ID` header is the idempotency key — re-submitting the same value returns the existing Strategy with its original `id` and `created_at`.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTradeStrategyBody'
      responses:
        '201':
          description: Strategy created. Body is the created Strategy. On idempotent re-submission, the original Strategy is returned and the status code may be `200` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
    get:
      tags:
      - Trade Strategy
      summary: List Strategies
      description: Lists all Strategies under your platform, paginated. Synchronous.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: page_token
        in: query
        required: false
        schema:
          type: string
        description: Opaque cursor from a prior response's `next_page_token`. Empty / missing = first page.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Items per page. Capped at 200. Defaults to 50.
      responses:
        '200':
          description: Paginated list of Strategies (possibly empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTradeStrategiesResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/{strategy_id}:
    get:
      tags:
      - Trade Strategy
      summary: Get a Strategy
      description: Retrieves a single Strategy by its `id`. Synchronous.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Strategy.
      responses:
        '200':
          description: The requested Strategy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Strategy doesn't exist or belongs to a different platform.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
    patch:
      tags:
      - Trade Strategy
      summary: Update a Strategy's metadata
      description: Updates the Strategy's `metadata`. Synchronous. The submitted value replaces the previous one verbatim (no merge); pass `{}` to clear. Only `metadata` is mutable.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Strategy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTradeStrategyBody'
      responses:
        '200':
          description: The updated Strategy.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Strategy doesn't exist or belongs to a different platform.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/{strategy_id}/enroll:
    post:
      tags:
      - Trade Strategy
      summary: Enroll participants
      description: Submits a new enrollment Operation. Asynchronous. Each participant is processed independently; participant-level failures do not block the others. Idempotent on (strategy_id, `X-REQUEST-ID`).
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Strategy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTradeStrategyEnrollmentBody'
      responses:
        '202':
          description: Operation accepted and queued for processing. Body is the Operation in its initial `validating` status. Poll `GET /strategies/operations/{operation_id}` or subscribe to webhooks to observe the terminal status. On idempotent re-submission the existing Operation is returned and the status code may be `200` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyOperationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Strategy not found.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/{strategy_id}/top-up:
    post:
      tags:
      - Trade Strategy
      summary: Top up participants
      description: Adds fiat to one or more existing Traders' positions and buys proportionally to the supplied allocations. Asynchronous. Idempotent on (strategy_id, `X-REQUEST-ID`).
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Strategy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTradeStrategyTopUpBody'
      responses:
        '202':
          description: Operation accepted and queued for processing. Body is the Operation in its initial `validating` status. Poll `GET /strategies/operations/{operation_id}` or subscribe to webhooks to observe the terminal status. On idempotent re-submission the existing Operation is returned and the status code may be `200` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyOperationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Strategy not found.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/{strategy_id}/partial-sell:
    post:
      tags:
      - Trade Strategy
      summary: Partial sell
      description: 'Executes a partial sell for one or more existing Traders. `amount` is the fiat the Trader wants back; sells are sized proportionally to the supplied allocations. Asynchronous. PartialSell does NOT produce `skipped` outcomes — a participant whose per-asset slice falls below the instrument minimum gets an Execution with `status: "rejected"` and `status_reason: "below_instrument_minimum"`.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Strategy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTradeStrategyPartialSellBody'
      responses:
        '202':
          description: Operation accepted and queued for processing. Body is the Operation in its initial `validating` status. Poll `GET /strategies/operations/{operation_id}` or subscribe to webhooks to observe the terminal status. On idempotent re-submission the existing Operation is returned and the status code may be `200` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyOperationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Strategy not found.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/{strategy_id}/liquidate:
    post:
      tags:
      - Trade Strategy
      summary: Liquidate participants
      description: Fully exits one or more participants from the Strategy by selling everything they currently hold. Asynchronous. No allocations or per-participant amount — zerohash reads each participant's current balance and sells whatever they hold.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Strategy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTradeStrategyLiquidationBody'
      responses:
        '202':
          description: Operation accepted and queued for processing. Body is the Operation in its initial `validating` status. Poll `GET /strategies/operations/{operation_id}` or subscribe to webhooks to observe the terminal status. On idempotent re-submission the existing Operation is returned and the status code may be `200` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyOperationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Strategy not found.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/{strategy_id}/rebalance:
    post:
      tags:
      - Trade Strategy
      summary: Rebalance
      description: 'Re-aligns Traders to the supplied allocations. Asynchronous. If `participants` is omitted, every Trader with `auto_rebalance: true` is targeted; if provided, only those Traders are targeted (ignoring their `auto_rebalance` flag). A weight of `"0"` means "fully exit this asset"; assets the Trader currently holds that are missing from the list are also fully exited.'
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Strategy.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTradeStrategyRebalanceBody'
      responses:
        '202':
          description: Operation accepted and queued for processing. Body is the Operation in its initial `validating` status. Poll `GET /strategies/operations/{operation_id}` or subscribe to webhooks to observe the terminal status. On idempotent re-submission the existing Operation is returned and the status code may be `200` instead.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyOperationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Strategy not found.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/operations:
    get:
      tags:
      - Trade Strategy
      summary: List Operations
      description: Lists Operations across one or more Strategies, paginated. Synchronous.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: query
        schema:
          type: string
        description: Filter Operations to a single Strategy.
      - name: request_id
        in: query
        schema:
          type: string
        description: Filter by the platform's `request_id` on the Operation (idempotency key lookup — not the per-call correlation id).
      - name: type
        in: query
        schema:
          type: string
          enum:
          - enrollment
          - top_up
          - partial_sell
          - rebalance
          - liquidation
      - name: status
        in: query
        schema:
          type: string
          enum:
          - validating
          - pricing
          - settling
          - settled
          - skipped
          - failed
      - name: page_token
        in: query
        required: false
        schema:
          type: string
        description: Opaque cursor from a prior response's `next_page_token`. Empty / missing = first page.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Items per page. Capped at 200. Defaults to 50.
      responses:
        '200':
          description: Paginated list of Operations (possibly empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTradeStrategyOperationsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/operations/{operation_id}:
    get:
      tags:
      - Trade Strategy
      summary: Get an Operation
      description: Retrieves a single Operation by its `id`. Use this to poll until `status` is terminal (`settled`, `skipped`, or `failed`) — or subscribe to webhooks and skip the polling.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: operation_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Operation.
      responses:
        '200':
          description: The requested Operation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyOperationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Operation doesn't exist or belongs to a different platform.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/traders:
    get:
      tags:
      - Trade Strategy
      summary: List Traders
      description: Lists Traders across one or more Strategies, paginated. Synchronous.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: query
        schema:
          type: string
        description: Filter Traders to a single Strategy.
      - name: participant_code
        in: query
        schema:
          type: string
        description: Filter Traders to a single end customer.
      - name: auto_rebalance
        in: query
        schema:
          type: string
          enum:
          - 'true'
          - 'false'
        description: Filter Traders by their `auto_rebalance` flag.
      - name: page_token
        in: query
        required: false
        schema:
          type: string
        description: Opaque cursor from a prior response's `next_page_token`. Empty / missing = first page.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Items per page. Capped at 200. Defaults to 50.
      responses:
        '200':
          description: Paginated list of Traders (possibly empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTradeStrategyTradersResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/traders/{trader_id}:
    get:
      tags:
      - Trade Strategy
      summary: Get a Trader
      description: Retrieves a single Trader by its `id`. Synchronous.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: trader_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Trader.
      responses:
        '200':
          description: The requested Trader.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyTraderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Trader doesn't exist or belongs to a different platform.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
    patch:
      tags:
      - Trade Strategy
      summary: Update a Trader's settings
      description: Updates a Trader's settings. Synchronous. Currently the only mutable field is `auto_rebalance`. Does not affect any in-flight Operation; takes effect on the next Rebalance.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: trader_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Trader.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateTradeStrategyTraderBody'
      responses:
        '200':
          description: The updated Trader.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyTraderResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Trader not found.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/executions:
    get:
      tags:
      - Trade Strategy
      summary: List Executions
      description: Lists Executions across one or more Strategies, paginated. Each Execution includes the full `instructions[]` array, which can be large — narrow with filters whenever possible. Synchronous.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: strategy_id
        in: query
        schema:
          type: string
        description: Filter Executions to a single Strategy.
      - name: operation_id
        in: query
        schema:
          type: string
        description: Filter Executions to a single Operation.
      - name: participant_code
        in: query
        schema:
          type: string
        description: Filter Executions to a single end customer.
      - name: status
        in: query
        schema:
          type: string
          enum:
          - awaiting_execution
          - settled
          - skipped
          - rejected
      - name: page_token
        in: query
        required: false
        schema:
          type: string
        description: Opaque cursor from a prior response's `next_page_token`. Empty / missing = first page.
      - name: page_size
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 200
        description: Items per page. Capped at 200. Defaults to 50.
      responses:
        '200':
          description: Paginated list of Executions (possibly empty).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTradeStrategyExecutionsResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code404'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
  /strategies/executions/{execution_id}:
    get:
      tags:
      - Trade Strategy
      summary: Get an Execution
      description: Retrieves a single Execution by its `id`. Synchronous. Includes the full `instructions[]` array.
      parameters:
      - $ref: '#/components/parameters/Signature'
      - $ref: '#/components/parameters/Timestamp'
      - name: execution_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
        description: Unique identifier of the Execution.
      responses:
        '200':
          description: The requested Execution.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TradeStrategyExecutionResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code400'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code403'
        '404':
          description: Execution doesn't exist or belongs to a different platform.
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code500'
        '503':
          description: Service Unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Code503'
components:
  schemas:
    Code400:
      type: object
      description: Request was rejected by validation or a downstream service. `errors` is an array of human

# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/zero-hash/refs/heads/main/openapi/zero-hash-trade-strategy-api-openapi.yml