> ## 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.

# Get traders linked by a shared device or IP address

> Groups of your traders who used the same device or IP address, to spot one person running several trader profiles or several people sharing one account.

Two traders are linked when they were seen on the same device or IP address in the period; links are merged into groups, so A–B and B–C form one group of three. Traders are grouped by login, and only their activity since they first had an account with you counts. Activity at other firms is never included.

Each group has a `score` from 0 to 100, its strongest link between two traders. A shared device weighs more than a shared IP address, an IP address shared by two traders more than one shared by several, and every extra shared signal raises the score. A device or IP address used by more than `maxTradersPerSignal` traders is left out and listed in `noisySignals`.

Results are shared for about 15 minutes and can be up to 30 minutes old; `asOf` says when the activity was read.

## Example

```bash
curl "https://api.hyperprop.com/platform/v1/organization/risk/linked-traders?days=30&signal=all" \
  -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/linked-traders
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/linked-traders:
    get:
      tags:
        - Risk
      summary: Get traders linked by a shared device or IP address
      description: >-
        Groups of your traders who used the same device or IP address, to spot
        one person running several trader profiles or several people sharing one
        account.


        Two traders are linked when they were seen on the same device or IP
        address in the period; links are merged into groups, so A–B and B–C form
        one group of three. Traders are grouped by login, and only their
        activity since they first had an account with you counts. Activity at
        other firms is never included.


        Each group has a `score` from 0 to 100, its strongest link between two
        traders. A shared device weighs more than a shared IP address, an IP
        address shared by two traders more than one shared by several, and every
        extra shared signal raises the score. A device or IP address used by
        more than `maxTradersPerSignal` traders is left out and listed in
        `noisySignals`.


        Results are shared for about 15 minutes and can be up to 30 minutes old;
        `asOf` says when the activity was read.


        ## Example


        ```bash

        curl
        "https://api.hyperprop.com/platform/v1/organization/risk/linked-traders?days=30&signal=all"
        \
          -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: getV1OrganizationRiskLinkedtraders
      parameters:
        - description: Look back this many days, 1–90
          name: days
          in: query
          example: 30
          schema:
            type: integer
            minimum: 1
            maximum: 90
            default: 30
        - description: >-
            `device`: only shared devices; `ip`: only shared IP addresses;
            `all`: both
          name: signal
          in: query
          example: device
          schema:
            type: string
            enum:
              - all
              - device
              - ip
            default: all
        - description: Only groups with at least this many traders
          name: minTraders
          in: query
          example: 3
          schema:
            type: integer
            minimum: 2
            maximum: 50
            default: 2
        - description: >-
            Leave out a device or IP address used by more traders than this
            (mobile carriers, VPNs, offices); listed in `noisySignals` instead
          name: maxTradersPerSignal
          in: query
          example: 10
          schema:
            type: integer
            minimum: 2
            maximum: 50
            default: 10
        - description: Most groups to return
          name: limit
          in: query
          example: 50
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
        - 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: >-
            Groups of linked traders with the shared devices and IP addresses
            and their accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Model666'
        '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: this endpoint allows 60 calls per minute per
            organization. Wait the number of seconds in the `Retry-After`
            header. Also returned while your organization already has 6 reports
            being computed at once; wait the `Retry-After` seconds.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    description: Always false on errors
                    example: false
                  statusCode:
                    type: integer
                    example: 429
                  error:
                    type: string
                    example: Too Many Requests
                  message:
                    type: string
                    example: >-
                      Too many requests to this endpoint. Try again in 12
                      second(s).
                  code:
                    type: string
                    enum:
                      - RATE_LIMITED
                    example: RATE_LIMITED
                    description: >-
                      Machine-readable error code — switch on this, not on
                      message text
        '500':
          description: Internal error (`LINKED_TRADERS_ERROR`)
        '503':
          description: >-
            Not available yet (`LINKED_TRADERS_UNAVAILABLE`); try again later.
            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/Model667'
      security:
        - X-API-Key: []
components:
  schemas:
    Model666:
      type: object
      properties:
        success:
          type: boolean
          example: true
        data:
          $ref: '#/components/schemas/Model665'
    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
    Model667:
      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
    Model665:
      type: object
      properties:
        organizationId:
          type: string
          example: 55555555-5555-4555-8555-555555555555
        asOf:
          type: string
          description: When the underlying activity was read
          example: '2026-11-03T14:41:07.118Z'
          x-format:
            isoDate: true
        redacted:
          type: boolean
          description: >-
            True when device ids and IP addresses are shortened (203.0.113.x,
            dev…a91c) because your role lacks Risk investigations
          example: false
        days:
          type: integer
          example: 30
        signal:
          $ref: '#/components/schemas/signal'
        minTraders:
          type: integer
          example: 2
        maxTradersPerSignal:
          type: integer
          example: 10
        summary:
          $ref: '#/components/schemas/Model652'
        clusters:
          $ref: '#/components/schemas/clusters'
        noisySignals:
          $ref: '#/components/schemas/noisySignals'
    signal:
      type: string
      example: all
      enum:
        - all
        - device
        - ip
    Model652:
      type: object
      description: Totals over every group, not only the `limit` returned
      properties:
        clusters:
          type: integer
          example: 4
        traders:
          type: integer
          example: 9
        accounts:
          type: integer
          example: 23
        fundedAccounts:
          type: integer
          example: 3
        highStrength:
          type: integer
          example: 1
        noisySignals:
          type: integer
          description: Signals left out because too many traders share them
          example: 2
        truncated:
          type: boolean
          description: >-
            True when the period held more activity than one read covers;
            shorten `days`
          example: false
    clusters:
      type: array
      description: Strongest first
      items:
        $ref: '#/components/schemas/Model662'
    noisySignals:
      type: array
      description: Up to 20 left-out signals, most shared first
      items:
        $ref: '#/components/schemas/Model664'
    Model662:
      type: object
      properties:
        clusterId:
          type: string
          description: Stable while the group's members stay the same
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        score:
          type: integer
          description: Strongest link between two traders in the group, 0–100
          example: 82
          minimum: 0
          maximum: 100
        strength:
          $ref: '#/components/schemas/strength'
        traderCount:
          type: integer
          example: 2
        accountCount:
          type: integer
          example: 5
        fundedAccountCount:
          type: integer
          example: 1
        sharedDevices:
          type: integer
          example: 1
        sharedIps:
          type: integer
          example: 2
        lastSeenAt:
          type: string
          example: '2026-11-02T21:40:03.000Z'
          x-format:
            isoDate: true
        traders:
          $ref: '#/components/schemas/Model656'
        signals:
          $ref: '#/components/schemas/signals'
        links:
          $ref: '#/components/schemas/links'
    Model664:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Model663'
        value:
          type: string
          example: 203.0.113.7
        traderCount:
          type: integer
          example: 37
    strength:
      type: string
      description: '`high` from 70, `medium` from 40, else `low`'
      example: high
      enum:
        - high
        - medium
        - low
    Model656:
      type: array
      items:
        $ref: '#/components/schemas/Model655'
    signals:
      type: array
      description: Devices first, then IP addresses
      items:
        $ref: '#/components/schemas/Model660'
    links:
      type: array
      description: Each pair of traders that share something directly, strongest first
      items:
        $ref: '#/components/schemas/Model661'
    Model663:
      type: string
      example: ip
      enum:
        - device
        - ip
    Model655:
      type: object
      properties:
        userId:
          type: string
          description: >-
            The trader's login; one login can hold several of your trader
            records and accounts
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
          x-format:
            guid: true
        traderName:
          type: string
          description: From your trader record on the login's most recent account
          example: Jane Trader
        traderEmail:
          type: string
          example: jane@example.com
        ownedSince:
          type: string
          description: >-
            When this login first had an account of yours; no earlier activity
            is considered
          example: '2026-09-14T10:02:11.000Z'
          x-format:
            isoDate: true
        sharedSignals:
          type: integer
          description: Devices and IP addresses this trader shares with others in the group
          example: 3
        firstSeenAt:
          type: string
          example: '2026-10-05T08:12:44.000Z'
          x-format:
            isoDate: true
        lastSeenAt:
          type: string
          example: '2026-11-02T21:40:03.000Z'
          x-format:
            isoDate: true
        accounts:
          $ref: '#/components/schemas/Model654'
    Model660:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/Model657'
        value:
          type: string
          description: Device identifier or IP address
          example: 4f1c2b9a7e6d5c3b
        traderCount:
          type: integer
          description: How many of your traders used it in the period
          example: 2
        traders:
          $ref: '#/components/schemas/Model659'
    Model661:
      type: object
      properties:
        userIds:
          $ref: '#/components/schemas/userIds'
        score:
          type: integer
          example: 82
        devices:
          type: integer
          example: 1
        ips:
          type: integer
          example: 2
    Model654:
      type: array
      description: Every account of yours this login holds
      items:
        $ref: '#/components/schemas/Model653'
    Model657:
      type: string
      example: device
      enum:
        - device
        - ip
    Model659:
      type: array
      items:
        $ref: '#/components/schemas/Model658'
    userIds:
      type: array
      example:
        - 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
        - 9a8b7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d
      x-constraint:
        length: 2
      items:
        type: string
        x-format:
          guid: true
    Model653:
      type: object
      properties:
        accountId:
          type: string
          example: 7c9e6679-7425-40de-944b-e07fc1f90ae7
          x-format:
            guid: true
        accountNumber:
          type: string
          example: ACC-50K-000123
        status:
          type: string
          example: in_progress
        accountType:
          type: string
          description: '`evaluation`, `sim_funded` or `competition`'
          example: sim_funded
        planId:
          type: string
          example: 7f8d9e0a-1b2c-3d4e-5f60-718293a4b5c6
          x-format:
            guid: true
        planName:
          type: string
          example: 50K Pro
        accountSize:
          type: number
          example: 50000
    Model658:
      type: object
      properties:
        userId:
          type: string
          example: 2b1f0c9e-4d3a-4e5f-8a7b-6c5d4e3f2a1b
          x-format:
            guid: true
        firstSeenAt:
          type: string
          example: '2026-10-05T08:12:44.000Z'
          x-format:
            isoDate: true
        lastSeenAt:
          type: string
          example: '2026-11-02T21:40:03.000Z'
          x-format:
            isoDate: true
        events:
          type: integer
          description: Sign-ins and device sessions seen with it
          example: 14
  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

- [Clear two traders to share a device or address](https://docs.hyperprop.com/platform-api/risk/clear-two-traders-to-share-a-device-or-address.md)
- [Get an account's event log and session history](https://docs.hyperprop.com/platform-api/trading-accounts/get-an-accounts-event-log-and-session-history.md)
- [Get a specific trader](https://docs.hyperprop.com/platform-api/traders/get-a-specific-trader.md)
- [Read the daily risk report of a trading day](https://docs.hyperprop.com/platform-api/risk/read-the-daily-risk-report-of-a-trading-day.md)
- [Read one trader's risk findings with their proof](https://docs.hyperprop.com/platform-api/risk/read-one-traders-risk-findings-with-their-proof.md)


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