> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperprop.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detect self-hedging, hedging and copy trading

> Finds trading patterns among your traders that prop-firm rules usually forbid. Only your organization's accounts are analyzed, and an account only from when it became its current trader's.

- **Self-hedging:** one trader holding opposite positions on the same underlying across their own accounts at the same time, for example long on one evaluation and short on another, or long MNQ against short NQ. `live` lists the positions held right now; `episodes` the past ones (at least 5 seconds of overlap).
- **Hedging pairs:** two different traders opening opposite positions on the same underlying within `windowSeconds` of each other, at least `minOccurrences` times.
- **Copy trading:** two different traders opening the same position within `windowSeconds`, repeatedly: an external trade copier, a signal group or a shared account. Copy trading a trader sets up across their own accounts on the platform is listed under `platformCopy` and never reported as a pair.

Micro and full-size contracts on the same underlying are compared (MNQ with NQ, MES with ES, MGC with GC and so on), with sizes in full-size contracts. Each pair and trader has a `score` from 0 to 100 and a `level`; a higher score means more of the activity matches, more often, closer in time and size. Scores flag accounts for review; they are not proof.

Moments when very many traders open the same product at once (`summary.crowdedMoments`, for example a market open) are not used for pairing.

The history is shared for up to 5 minutes per set of parameters; live self-hedges are a few seconds old at most. About 30 requests per minute per organization.

## Example

```bash
curl "https://api.hyperprop.com/platform/v1/organization/risk/trading-patterns?days=14&windowSeconds=5" \
  -H "X-API-Key: hp_live_your_key_here"
```

**Permissions:** requires **view** access to "Traders & accounts".

**Access:** read-only and full-access API keys. Dashboard members need view access to Traders & accounts.



## OpenAPI

````yaml https://api.hyperprop.com/platform/openapi.json get /v1/organization/risk/trading-patterns
openapi: 3.0.0
info:
  title: Hyperprop Platform API
  version: 1.0.0
  description: >-
    REST API for the Hyperprop Trading Platform — provision evaluation and
    funded trading accounts, manage traders and plans, react to account
    lifecycle events via signed webhooks, and reconcile billing. Built for prop
    firms integrating from their own backend.


    Authentication, quick start, error handling, idempotency, pagination, custom
    metadata, webhooks, and the MCP connector are documented at
    https://docs.hyperprop.com.
  x-logo:
    url: https://app.hyperprop.com/logo-icon.svg
    altText: Hyperprop
    href: https://hyperprop.com
servers:
  - url: https://api.hyperprop.com/platform
    description: Production
security: []
tags:
  - name: Trading accounts
    description: Create, update, and inspect trading accounts.
  - name: Traders
    description: Look up and update the traders in your organization.
  - name: Trading plans
    description: Define the plans you sell.
  - name: Trading rules
    description: Define how accounts are evaluated.
  - name: Instruments
    description: >-
      The contracts your organization's accounts can trade, with their
      specifications.
  - name: Lockouts
    description: Pause and resume trading on an account.
  - name: Payouts
    description: Check payout eligibility and record payouts.
  - name: Purchases
    description: Purchases recorded for your organization.
  - name: Time Machine
    description: Restore accounts to an earlier trading day or instant.
  - name: Mass credit
    description: >-
      Credit back losses across many accounts after an incident, as background
      jobs you can follow, pause, export and reverse.
  - name: Webhooks
    description: Register webhook endpoints and inspect deliveries.
  - name: Events
    description: Your organization's event history, to replay or audit what happened.
  - name: Real-time streams
    description: >-
      Live events and trading data over a WebSocket, for dashboards and CRMs
      that update as things happen.
  - name: Reconciliation
    description: Balances, end-of-day snapshots, and fills for reconciliation.
  - name: Analytics
    description: Organization performance, revenue and top traders.
  - name: Risk
    description: Firm profit and loss and plan economics.
  - name: Trader insights
    description: >-
      What your traders hold right now and over time, your top traders, and the
      traders you follow.
  - name: Billing and invoices
    description: >-
      Your Hyperprop invoices, credits and billing details, with usage so far
      this month, billing cycles, forecasts and CSV exports.
  - name: Team and roles
    description: Manage dashboard access for your staff.
  - name: API keys
    description: >-
      Manage your organization's API keys: rotation, read-only keys and IP
      allowlists.
  - name: Logs and health
    description: >-
      API request logs, the audit log, integration health, and idempotency key
      recovery.
  - name: Organization profile
    description: Your organization's profile and logo.
  - name: Support
    description: Open and follow up on support tickets.
  - name: Partner access
    description: >-
      Read a trader's journal as an approved partner app, with the trader's own
      key.
paths:
  /v1/organization/risk/trading-patterns:
    get:
      tags:
        - Risk
      summary: Detect self-hedging, hedging and copy trading
      description: >-
        Finds trading patterns among your traders that prop-firm rules usually
        forbid. Only your organization's accounts are analyzed, and an account
        only from when it became its current trader's.


        - **Self-hedging:** one trader holding opposite positions on the same
        underlying across their own accounts at the same time, for example long
        on one evaluation and short on another, or long MNQ against short NQ.
        `live` lists the positions held right now; `episodes` the past ones (at
        least 5 seconds of overlap).

        - **Hedging pairs:** two different traders opening opposite positions on
        the same underlying within `windowSeconds` of each other, at least
        `minOccurrences` times.

        - **Copy trading:** two different traders opening the same position
        within `windowSeconds`, repeatedly: an external trade copier, a signal
        group or a shared account. Copy trading a trader sets up across their
        own accounts on the platform is listed under `platformCopy` and never
        reported as a pair.


        Micro and full-size contracts on the same underlying are compared (MNQ
        with NQ, MES with ES, MGC with GC and so on), with sizes in full-size
        contracts. Each pair and trader has a `score` from 0 to 100 and a
        `level`; a higher score means more of the activity matches, more often,
        closer in time and size. Scores flag accounts for review; they are not
        proof.


        Moments when very many traders open the same product at once
        (`summary.crowdedMoments`, for example a market open) are not used for
        pairing.


        The history is shared for up to 5 minutes per set of parameters; live
        self-hedges are a few seconds old at most. About 30 requests per minute
        per organization.


        ## Example


        ```bash

        curl
        "https://api.hyperprop.com/platform/v1/organization/risk/trading-patterns?days=14&windowSeconds=5"
        \
          -H "X-API-Key: hp_live_your_key_here"
        ```


        **Permissions:** requires **view** access to "Traders & accounts".


        **Access:** read-only and full-access API keys. Dashboard members need
        view access to Traders & accounts.
      operationId: getV1OrganizationRiskTradingpatterns
      parameters:
        - description: Days of history to analyze, 1 to 30
          name: days
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 30
            default: 7
        - description: >-
            Most seconds between two traders' entries for them to count as
            together, 1 to 60
          name: windowSeconds
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 60
            default: 10
        - description: Fewest matched entries for a pair of traders to be reported
          name: minOccurrences
          in: query
          schema:
            type: integer
            minimum: 2
            maximum: 50
            default: 3
        - name: If-None-Match
          in: header
          required: false
          description: >-
            Optional. The `ETag` of the answer you already have. When the answer
            would be the same, the response is `304` without a body.
          example: '"Hq3mB1c0s8n2JkVbQy4Tz9uXw5E"'
          schema:
            type: string
      responses:
        '200':
          description: Self-hedging, hedging pairs and copy trading among your traders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model742'
        '304':
          description: >-
            Not modified: the answer is the same as the one whose `ETag` you
            sent in `If-None-Match`. No body; keep using the answer you have.
        '400':
          description: Invalid request data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model351'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model15'
        '403':
          description: This API key does not have admin permissions
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model511'
        '429':
          description: >-
            Too many requests for your organization (`RATE_LIMITED`); wait
            `retryAfterSeconds`. Also returned while your organization already
            has 6 reports being computed at once; wait the `Retry-After`
            seconds.
        '500':
          description: Internal error (`TRADING_PATTERNS_ERROR`)
        '503':
          description: >-
            Detection is not available yet (`TRADING_PATTERNS_UNAVAILABLE`). The
            report took too long right now (`REPORT_TIMEOUT`). Wait the seconds
            in the `Retry-After` header (also `retryAfterSeconds` in the body)
            before asking again; the wait grows while the report keeps running
            out of time.
        '504':
          description: >-
            Gateway Timeout - The request did not complete within 25 seconds
            (`REQUEST_TIMEOUT`). Nothing was changed; retry, or narrow the
            request (for example a shorter date range).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model743'
      security:
        - X-API-Key: []
components:
  schemas:
    Model742:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Model741'
    Model351:
      type: object
      properties:
        success:
          type: boolean
          description: Always false on errors
          example: false
        statusCode:
          type: number
          example: 400
        error:
          type: string
          example: Bad Request
        message:
          type: string
          example: Invalid request data
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: BAD_REQUEST
    Model15:
      type: object
      properties:
        success:
          type: boolean
          description: Always false on errors
          example: false
        statusCode:
          type: number
          example: 401
        error:
          type: string
          example: Unauthorized
        message:
          type: string
          example: Authentication required
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: UNAUTHORIZED
    Model511:
      type: object
      properties:
        success:
          type: boolean
          description: Always false on errors
          example: false
        statusCode:
          type: number
          example: 403
        error:
          type: string
          example: Forbidden
        message:
          type: string
          example: This API key does not have admin permissions
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: INSUFFICIENT_PERMISSIONS
    Model743:
      type: object
      properties:
        statusCode:
          type: number
          example: 504
        error:
          type: string
          example: Gateway Timeout
        message:
          type: string
          example: >-
            The request did not complete within 25 seconds. Try again, or narrow
            it (for example a shorter date range).
        code:
          type: string
          description: Machine-readable error code — switch on this, not on message text
          example: REQUEST_TIMEOUT
    Model741:
      type: object
      properties:
        organizationId:
          type: string
          example: 55555555-5555-4555-8555-555555555555
        asOf:
          type: string
          description: When the history was computed
          example: '2026-11-03T14:41:07.118Z'
        params:
          $ref: '#/components/schemas/params'
        selfHedging:
          $ref: '#/components/schemas/selfHedging'
        hedgingPairs:
          $ref: '#/components/schemas/hedgingPairs'
        copyTrading:
          $ref: '#/components/schemas/copyTrading'
        summary:
          $ref: '#/components/schemas/Model740'
    params:
      type: object
      properties:
        days:
          type: integer
          example: 7
        windowSeconds:
          type: integer
          example: 10
        minOccurrences:
          type: integer
          example: 3
        since:
          type: string
          example: '2026-10-27T14:41:07.118Z'
        until:
          type: string
          example: '2026-11-03T14:41:07.118Z'
    selfHedging:
      type: object
      properties:
        liveAvailable:
          type: boolean
          description: >-
            False when live positions could not be read; `live` is then empty,
            not clear
          example: true
        liveAsOf:
          type: string
          example: '2026-11-03T14:41:09.002Z'
        live:
          $ref: '#/components/schemas/Model724'
        traders:
          $ref: '#/components/schemas/Model729'
        episodes:
          $ref: '#/components/schemas/episodes'
        episodesTotal:
          type: integer
          example: 7
    hedgingPairs:
      type: array
      description: >-
        Pairs of traders opening opposite positions together, highest score
        first
      items:
        $ref: '#/components/schemas/Model736'
    copyTrading:
      type: object
      properties:
        pairs:
          $ref: '#/components/schemas/pairs'
        platformCopy:
          $ref: '#/components/schemas/platformCopy'
    Model740:
      type: object
      properties:
        fills:
          type: integer
          example: 18402
        entries:
          type: integer
          example: 7311
        crowdedMoments:
          type: integer
          description: >-
            Moments with so many traders opening the same product that they were
            not paired
          example: 3
        selfHedgingTraders:
          type: integer
          example: 2
        liveSelfHedges:
          type: integer
          example: 1
        hedgingPairs:
          type: integer
          example: 1
        copyPairs:
          type: integer
          example: 3
        platformCopyGroups:
          type: integer
          example: 5
    Model724:
      type: array
      description: Opposite positions held right now
      items:
        $ref: '#/components/schemas/Model723'
    Model729:
      type: array
      description: Traders who self-hedged, highest score first
      items:
        $ref: '#/components/schemas/Model728'
    episodes:
      type: array
      description: Most recent episodes, at most 1,000
      items:
        $ref: '#/components/schemas/Model730'
    Model736:
      type: object
      properties:
        traderA:
          $ref: '#/components/schemas/traderA'
        traderB:
          $ref: '#/components/schemas/traderA'
        underlyings:
          $ref: '#/components/schemas/Model732'
        occurrences:
          type: integer
          description: Matched entries, counted once per entry of the less matched trader
          example: 9
        matchedFills:
          type: integer
          example: 11
        activeDays:
          type: integer
          description: Trading days (America/Chicago) with a match
          example: 4
        avgSecondsApart:
          type: number
          example: 2.4
        similarSizeShare:
          type: number
          description: >-
            Share of matches whose sizes are within 20% of each other (in
            full-size contracts)
          example: 0.89
          minimum: 0
          maximum: 1
        firstAt:
          type: string
          example: '2026-10-28T13:30:02.000Z'
        lastAt:
          type: string
          example: '2026-11-03T14:05:41.000Z'
        samples:
          $ref: '#/components/schemas/samples'
        score:
          type: integer
          example: 76
          minimum: 0
          maximum: 100
        level:
          $ref: '#/components/schemas/Model735'
    pairs:
      type: array
      description: >-
        Pairs of traders opening the same positions together, highest score
        first
      items:
        $ref: '#/components/schemas/Model736'
    platformCopy:
      type: array
      description: >-
        Copy trading set up by a trader across their own accounts; never
        reported as a pair
      items:
        $ref: '#/components/schemas/Model739'
    Model723:
      type: object
      properties:
        traderId:
          type: string
          description: >-
            Your trader record when the account has one, otherwise the trader's
            login
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        traderName:
          type: string
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
        underlying:
          type: string
          description: 'Shared underlying: MNQ and NQ are both `NQ`'
          example: NQ
        hedgedSize:
          type: number
          description: >-
            Smaller of the long and short exposure, in full-size contracts (10
            MNQ = 1 NQ)
          example: 0.2
        since:
          type: string
          description: When both sides were first open together
          example: '2026-11-03T14:30:05.000Z'
        sameContract:
          type: boolean
          description: True when both sides hold the same contract
          example: false
        legs:
          $ref: '#/components/schemas/legs'
    Model728:
      type: object
      properties:
        traderId:
          type: string
          description: >-
            Your trader record when the account has one, otherwise the trader's
            login
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        traderName:
          type: string
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
        episodes:
          type: integer
          example: 4
        hedgedMinutes:
          type: number
          example: 96.5
        liveNow:
          type: boolean
          description: Holds opposite positions right now
          example: true
        underlyings:
          $ref: '#/components/schemas/underlyings'
        accounts:
          $ref: '#/components/schemas/Model726'
        lastAt:
          type: string
          example: '2026-11-03T14:41:07.118Z'
        score:
          type: integer
          example: 82
          minimum: 0
          maximum: 100
        level:
          $ref: '#/components/schemas/Model727'
    Model730:
      type: object
      properties:
        traderId:
          type: string
          description: >-
            Your trader record when the account has one, otherwise the trader's
            login
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        traderName:
          type: string
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
        underlying:
          type: string
          example: NQ
        accountA:
          $ref: '#/components/schemas/Model725'
        accountB:
          $ref: '#/components/schemas/accountB'
        sideA:
          $ref: '#/components/schemas/sideA'
        contractsA:
          $ref: '#/components/schemas/contractsA'
        contractsB:
          $ref: '#/components/schemas/contractsB'
        sameContract:
          type: boolean
          example: false
        startedAt:
          type: string
          example: '2026-11-02T14:00:05.000Z'
        endedAt:
          type: string
          example: '2026-11-02T14:30:00.000Z'
        ongoing:
          type: boolean
          description: Still open when the report was computed
          example: false
        durationSeconds:
          type: integer
          example: 1795
        maxHedgedSize:
          type: number
          description: Largest offsetting size during the episode, in full-size contracts
          example: 0.2
    traderA:
      type: object
      properties:
        traderId:
          type: string
          description: >-
            Your trader record when the account has one, otherwise the trader's
            login
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        traderName:
          type: string
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
        accounts:
          $ref: '#/components/schemas/Model731'
        entries:
          type: integer
          description: >-
            Positions this trader opened in the period, excluding platform copy
            trading
          example: 12
    Model732:
      type: array
      example:
        - ES
      items:
        type: string
    samples:
      type: array
      description: Most recent matches, at most 5
      items:
        $ref: '#/components/schemas/Model734'
    Model735:
      type: string
      example: high
      enum:
        - high
        - medium
        - low
    Model739:
      type: object
      properties:
        trader:
          $ref: '#/components/schemas/Model737'
        groupName:
          type: string
          example: default
        leader:
          $ref: '#/components/schemas/Model725'
        followers:
          $ref: '#/components/schemas/followers'
        crossOwner:
          type: boolean
          description: True when the leader and a follower now belong to different traders
          example: false
    legs:
      type: array
      items:
        $ref: '#/components/schemas/Model722'
    underlyings:
      type: array
      example:
        - ES
        - NQ
      items:
        type: string
    Model726:
      type: array
      items:
        $ref: '#/components/schemas/Model725'
    Model727:
      type: string
      example: high
      enum:
        - high
        - medium
        - low
    Model725:
      type: object
      properties:
        accountId:
          type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          x-format:
            guid: true
        accountNumber:
          type: string
          example: ACC-50K-000123
        accountType:
          type: string
          description: '`evaluation`, `sim_funded` or `competition`'
          example: evaluation
        status:
          type: string
          example: in_progress
        planName:
          type: string
          example: 50K Pro
        accountSize:
          type: number
          example: 50000
    accountB:
      type: object
      properties:
        accountNumber:
          type: string
          example: ACC-50K-000123
        accountType:
          type: string
          description: '`evaluation`, `sim_funded` or `competition`'
          example: evaluation
        status:
          type: string
          example: in_progress
        planName:
          type: string
          example: 50K Pro
        accountSize:
          type: number
          example: 50000
        accountId:
          type: string
          example: 9d1e6679-7425-40de-944b-e07fc1f90ae8
          x-format:
            guid: true
    sideA:
      type: string
      description: Side of account A; account B held the other side
      example: long
      enum:
        - long
        - short
    contractsA:
      type: array
      example:
        - MNQZ6
      items:
        type: string
    contractsB:
      type: array
      example:
        - NQZ6
      items:
        type: string
    Model731:
      type: array
      description: This trader's accounts in the matched trades (at most 20)
      items:
        $ref: '#/components/schemas/Model725'
    Model734:
      type: object
      properties:
        atA:
          type: string
          example: '2026-11-03T14:05:39.000Z'
        atB:
          type: string
          example: '2026-11-03T14:05:41.000Z'
        accountA:
          type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          x-format:
            guid: true
        accountB:
          type: string
          example: 9d1e6679-7425-40de-944b-e07fc1f90ae8
          x-format:
            guid: true
        underlying:
          type: string
          example: ES
        sideA:
          $ref: '#/components/schemas/Model733'
        sideB:
          $ref: '#/components/schemas/sideB'
        secondsApart:
          type: number
          example: 2
    Model737:
      type: object
      properties:
        traderId:
          type: string
          description: >-
            Your trader record when the account has one, otherwise the trader's
            login
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        traderName:
          type: string
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
    followers:
      type: array
      items:
        $ref: '#/components/schemas/Model738'
    Model722:
      type: object
      properties:
        accountId:
          type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          x-format:
            guid: true
        accountNumber:
          type: string
          example: ACC-50K-000123
        accountType:
          type: string
          description: '`evaluation`, `sim_funded` or `competition`'
          example: evaluation
        status:
          type: string
          example: in_progress
        planName:
          type: string
          example: 50K Pro
        accountSize:
          type: number
          example: 50000
        contract:
          type: string
          example: MNQZ6
        side:
          $ref: '#/components/schemas/side'
        quantity:
          type: number
          example: 2
        openedAt:
          type: string
          example: '2026-11-03T14:30:00.000Z'
    Model733:
      type: string
      example: buy
      enum:
        - buy
        - sell
    sideB:
      type: string
      example: sell
      enum:
        - buy
        - sell
    Model738:
      type: object
      properties:
        accountNumber:
          type: string
          example: ACC-50K-000123
        accountType:
          type: string
          description: '`evaluation`, `sim_funded` or `competition`'
          example: evaluation
        status:
          type: string
          example: in_progress
        planName:
          type: string
          example: 50K Pro
        accountSize:
          type: number
          example: 50000
        accountId:
          type: string
          example: 9d1e6679-7425-40de-944b-e07fc1f90ae8
          x-format:
            guid: true
        ratio:
          type: number
          example: 1
        symbol:
          type: string
          description: Contract the link copies; `*` for every contract
          example: '*'
        active:
          type: boolean
          example: true
        copiedFills:
          type: integer
          description: Copied fills in the period
          example: 14
        lastCopiedAt:
          type: string
          example: '2026-11-03T14:05:40.000Z'
    side:
      type: string
      example: long
      enum:
        - long
        - short
  securitySchemes:
    X-API-Key:
      type: apiKey
      name: X-API-Key
      in: header
      description: >-
        Organization API key (`hp_live_...`), sent in the `X-API-Key` header.
        Create, rotate and restrict keys in the dashboard or with the API keys
        endpoints; an organization can have two active keys, so you can rotate
        without downtime. A **full-access** key can call every endpoint in this
        reference. A **read-only** key can call `GET` endpoints (and create a
        trading stream token); any other request returns `403 READ_ONLY_KEY`. A
        key with an IP allowlist returns `403 IP_NOT_ALLOWED` from any other
        address. Each endpoint lists which keys can call it under **Access**.

````

## Related topics

- [List stored trading patterns](https://docs.hyperprop.com/platform-api/risk/list-stored-trading-patterns.md)
- [Delete a copy trading config](https://docs.hyperprop.com/trade-api/copy-trading/delete-a-copy-trading-config.md)
- [Get copy trading configuration](https://docs.hyperprop.com/trade-api/copy-trading/get-copy-trading-configuration.md)
- [Get copy trading status and positions](https://docs.hyperprop.com/trade-api/copy-trading/get-copy-trading-status-and-positions.md)
- [Delete all copy trading configs](https://docs.hyperprop.com/trade-api/copy-trading/delete-all-copy-trading-configs.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.