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

# public/margin_watch

> Calculates the mark-to-market value and initial/maintenance margin for a given subaccount, with per-position and per-collateral breakdowns, computed from live feed data at request time. Margins are reported on the margin basis actually in effect: when a delayed-liquidation override is active the response's is_delayed_liquidation flag is true and the reported margins use the temporarily lowered requirements. A maintenance margin below zero means the subaccount is flagged for liquidation.



## OpenAPI

````yaml /openapi.json post /public/margin_watch
openapi: 3.1.0
info:
  title: Derive v3 API
  version: 0.2.0
  description: JSON-RPC 2.0 methods, served over WebSocket and HTTP POST.
servers:
  - url: https://api.derive.xyz/v3
    description: Production (HTTP POST base)
  - url: https://testnet.api.derive.xyz/v3
    description: Testnet (HTTP POST base)
security: []
tags:
  - name: Subaccounts
    description: >-
      List, inspect, and label subaccounts, portfolios, positions, and
      collateral.
  - name: Session Keys
    description: Register, edit, and list delegated signing keys.
  - name: Account
    description: Wallet-level account information and settings.
  - name: Orderbook
    description: Place, replace, cancel, and query orders, trigger orders, and algos.
  - name: RFQ
    description: 'Request-for-quote: send RFQs, quote, and execute block trades.'
  - name: Vault Shareholders
    description: >-
      Deposit into and withdraw from vaults, and track shares, requests, and
      performance.
  - name: Vault Curators
    description: >-
      Create and operate curated vaults: settle deposit and withdrawal requests,
      and manage vault metadata.
  - name: History
    description: >-
      Per-account historical records: orders, trades, transfers, and
      settlements.
  - name: Market Maker Protection
    description: Configure, read, and reset market-maker protection.
  - name: Transfers & Withdrawals
    description: Move collateral between subaccounts, to other wallets, and on-chain.
  - name: Onchain Actions
    description: >-
      L1 onchain actions submitted via OnchainActionManager: register deposit
      addresses, list pending deposits, and inspect onchain action history.
  - name: System
    description: Rate limits and transaction lookups.
  - name: Market Data
    description: Instruments, currencies, tickers, and market-wide feeds.
  - name: Referrals
    description: Referral codes and program performance.
  - name: Other
    description: Uncategorized.
paths:
  /public/margin_watch:
    post:
      tags:
        - Subaccounts
      summary: public/margin_watch
      description: >-
        Calculates the mark-to-market value and initial/maintenance margin for a
        given subaccount, with per-position and per-collateral breakdowns,
        computed from live feed data at request time. Margins are reported on
        the margin basis actually in effect: when a delayed-liquidation override
        is active the response's is_delayed_liquidation flag is true and the
        reported margins use the temporarily lowered requirements. A maintenance
        margin below zero means the subaccount is flagged for liquidation.
      operationId: public_margin_watch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarginWatchRequest'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicMarginWatchResponse'
        default:
          description: JSON-RPC error (see Error Codes)
components:
  schemas:
    MarginWatchRequest:
      type: object
      required:
        - subaccount_id
      properties:
        subaccount_id:
          type: integer
          format: uint64
          minimum: 0
      additionalProperties: false
    PublicMarginWatchResponse:
      description: >-
        Result of `public/margin_watch`: the margin state a liquidation watcher
        needs, computed on the margin basis actually in effect (a delayed-
        liquidation override, when installed, is already applied).
      type: object
      required:
        - collaterals
        - currency
        - initial_margin
        - is_delayed_liquidation
        - maintenance_margin
        - margin_type
        - positions
        - risk_universe_id
        - subaccount_id
        - subaccount_value
        - valuation_timestamp
      properties:
        collaterals:
          type: array
          items:
            $ref: '#/components/schemas/Collateral'
        currency:
          type: array
          items:
            type: string
        initial_margin:
          type: string
        is_delayed_liquidation:
          description: >-
            `true` when a delayed-liquidation margin override is active, i.e.
            the margins above are computed on the temporarily lowered basis.
          type: boolean
        maintenance_margin:
          description: Below zero the subaccount is flagged for liquidation.
          type: string
        margin_type:
          type: string
        positions:
          type: array
          items:
            $ref: '#/components/schemas/Position'
        risk_universe_id:
          type: integer
          format: uint32
          minimum: 0
        subaccount_id:
          type: integer
          format: uint64
          minimum: 0
        subaccount_value:
          type: string
        valuation_timestamp:
          description: Unix seconds at which margin and MtM were computed.
          type: integer
          format: int64
    Collateral:
      type: object
      required:
        - amount
        - amount_step
        - asset_name
        - asset_type
        - average_price
        - average_price_excl_fees
        - creation_timestamp
        - cumulative_interest
        - currency
        - delta
        - delta_currency
        - initial_margin
        - maintenance_margin
        - mark_price
        - mark_value
        - open_orders_margin
        - pending_interest
        - realized_pnl
        - realized_pnl_excl_fees
        - total_fees
        - unrealized_pnl
        - unrealized_pnl_excl_fees
      properties:
        amount:
          type: string
        amount_step:
          type: string
        asset_name:
          type: string
        asset_type:
          type: string
        average_price:
          type: string
        average_price_excl_fees:
          type: string
        creation_timestamp:
          type: integer
          format: int64
        cumulative_interest:
          type: string
        currency:
          type: string
        delta:
          type: string
        delta_currency:
          type: string
        initial_margin:
          type: string
        maintenance_margin:
          type: string
        mark_price:
          type: string
        mark_value:
          type: string
        open_orders_margin:
          type: string
        pending_interest:
          type: string
        realized_pnl:
          type: string
        realized_pnl_excl_fees:
          type: string
        total_fees:
          type: string
        unrealized_pnl:
          type: string
        unrealized_pnl_excl_fees:
          type: string
    Position:
      type: object
      required:
        - amount
        - amount_step
        - average_price
        - average_price_excl_fees
        - creation_timestamp
        - cumulative_funding
        - delta
        - gamma
        - index_price
        - initial_margin
        - instrument_name
        - instrument_type
        - maintenance_margin
        - mark_price
        - mark_value
        - net_settlements
        - open_orders_margin
        - pending_funding
        - realized_pnl
        - realized_pnl_excl_fees
        - theta
        - total_fees
        - unrealized_pnl
        - unrealized_pnl_excl_fees
        - vega
      properties:
        amount:
          type: string
        amount_step:
          type: string
        average_price:
          type: string
        average_price_excl_fees:
          type: string
        creation_timestamp:
          type: integer
          format: int64
        cumulative_funding:
          type: string
        delta:
          type: string
        gamma:
          type: string
        index_price:
          type: string
        initial_margin:
          type: string
        instrument_name:
          type: string
        instrument_type:
          $ref: '#/components/schemas/AssetType'
        leverage:
          type:
            - string
            - 'null'
        liquidation_price:
          type:
            - string
            - 'null'
        maintenance_margin:
          type: string
        mark_price:
          type: string
        mark_value:
          type: string
        net_settlements:
          type: string
        open_orders_margin:
          type: string
        pending_funding:
          type: string
        realized_pnl:
          type: string
        realized_pnl_excl_fees:
          type: string
        theta:
          type: string
        total_fees:
          type: string
        unrealized_pnl:
          type: string
        unrealized_pnl_excl_fees:
          type: string
        vega:
          type: string
    AssetType:
      description: 'Asset type of the instrument: `"option"`, `"perp"`, or `"erc20"`.'
      type: string
      enum:
        - option
        - perp
        - erc20

````

## Related topics

- [Margin watch](/api-reference/channels/marginwatch.md)
- [Auctions watch](/api-reference/channels/auctionswatch.md)
- [Subscriptions](/subscriptions.md)