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

# Get Cross Margin Liquidation

> Gets detailed liquidation data for an XM customer. Returns the active or most recent liquidation by default.



## OpenAPI

````yaml get /v1/entities/{entity_id}/cross_margin/liquidation
openapi: 3.0.1
info:
  title: REST API
  description: >-
    The Coinbase Prime REST API provides programmatic access to trading,
    custody, staking, market data, and account management functionality.
  version: '0.1'
servers:
  - url: https://api.prime.coinbase.com/
security: []
tags:
  - name: PrimeRESTAPI
paths:
  /v1/entities/{entity_id}/cross_margin/liquidation:
    get:
      tags:
        - Financing
      summary: Get Cross Margin Liquidation
      description: >-
        Gets detailed liquidation data for an XM customer. Returns the active or
        most recent liquidation by default.
      operationId: PrimeRESTAPI_GetXMLiquidation
      parameters:
        - name: entity_id
          in: path
          description: XM customer Prime Entity ID
          required: true
          schema:
            type: string
        - name: liquidation_id
          in: query
          description: >-
            Financing liquidation UUID. If omitted, returns the active or most
            recent liquidation.
          schema:
            type: string
      responses:
        '200':
          description: A successful response.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/coinbase.public_rest_api.GetXMLiquidationResponse
components:
  schemas:
    coinbase.public_rest_api.GetXMLiquidationResponse:
      title: >-
        GetXMLiquidationResponse contains detailed information about an XM
        liquidation
      type: object
      properties:
        liquidation:
          $ref: '#/components/schemas/coinbase.public_rest_api.XMLiquidationDetail'
    coinbase.public_rest_api.XMLiquidationDetail:
      title: >-
        XMLiquidationDetail provides detailed information about a single XM
        liquidation
      type: object
      properties:
        liquidation_id:
          type: string
          description: Financing liquidation UUID
          example: 63a2577a-930d-413b-81e4-9e77765da8f9
        status:
          $ref: '#/components/schemas/coinbase.public_rest_api.XMLiquidationStatus'
        shortfall_amount:
          type: string
          description: USD notional shortfall amount that triggered the liquidation
          example: '32083.26'
        pre_liquidation_start_time:
          type: string
          description: Timestamp when the pre-liquidation phase started
          format: date-time
        margin_summary:
          $ref: '#/components/schemas/coinbase.public_rest_api.XMSummary'
        liquidation_start_time:
          type: string
          description: Timestamp when active liquidation started
          format: date-time
        filled_amount:
          type: string
          description: USD notional amount that has been filled so far
          example: '15000.00'
        remaining_amount:
          type: string
          description: USD notional amount remaining to be liquidated
          example: '17083.26'
        liquidation_finish_time:
          type: string
          description: Timestamp when the liquidation finished
          format: date-time
        asset_breakdown:
          type: array
          description: Per-asset breakdown of liquidated amounts
          items:
            $ref: '#/components/schemas/coinbase.public_rest_api.XMLiquidatedAsset'
    coinbase.public_rest_api.XMLiquidationStatus:
      title: XMLiquidationStatus is the current status of an XM liquidation
      type: string
      description: >-
        - XM_LIQUIDATION_STATUS_PRE_LIQUIDATION: Liquidation is in the
        pre-liquidation phase
         - XM_LIQUIDATION_STATUS_LIQUIDATING: Liquidation is actively in progress
         - XM_LIQUIDATION_STATUS_LIQUIDATED: Liquidation has completed successfully
         - XM_LIQUIDATION_STATUS_CANCELED: Liquidation was canceled
         - XM_LIQUIDATION_STATUS_FAILED: Liquidation failed
      default: XM_LIQUIDATION_STATUS_UNSET
      enum:
        - XM_LIQUIDATION_STATUS_UNSET
        - XM_LIQUIDATION_STATUS_PRE_LIQUIDATION
        - XM_LIQUIDATION_STATUS_LIQUIDATING
        - XM_LIQUIDATION_STATUS_LIQUIDATED
        - XM_LIQUIDATION_STATUS_CANCELED
        - XM_LIQUIDATION_STATUS_FAILED
    coinbase.public_rest_api.XMSummary:
      title: >-
        XMSummary is the realtime evaluated XM margin model, containing
        positions and netting info
      type: object
      properties:
        margin_requirement:
          type: string
          description: Cross Margin Margin Requirement (XMMR) notional
          example: '10362.72'
        account_equity:
          type: string
          description: Equity notional
          example: '-21542.63'
        margin_excess_shortfall:
          type: string
          description: Equity - XMMR (margin excess is > 0)
          example: '-31891.67'
        consumed_credit:
          type: string
          description: Credit consumed from Cross Margin Credit Limit (XMCL)
          example: '22906.34'
        xm_credit_limit:
          type: string
          description: >-
            XM Credit Limit (XMCL) is the maximum notional USD of total fiat and
            digital asset loans
          example: '1222322.00'
        xm_margin_limit:
          type: string
          description: XM Margin Limit (XMML) is the maximum notional USD deficit
          example: '22123.00'
        spot_equity:
          type: string
          description: Equity attributed by spot
          example: '-21505.91'
        futures_equity:
          type: string
          description: Equity attributed by futures
          example: '-36.71'
        risk_netting_info:
          $ref: '#/components/schemas/coinbase.public_rest_api.XMRiskNettingInfo'
    coinbase.public_rest_api.XMLiquidatedAsset:
      title: XMLiquidatedAsset provides per-asset detail for a liquidation
      type: object
      properties:
        asset:
          type: string
          description: Asset currency
          example: BTC
        liquidated_amount:
          type: string
          description: Amount (nominal) of the asset that has been liquidated
          example: '0.1'
        liquidated_notional:
          type: string
          description: USD notional value of the liquidated amount
          example: '11453.17'
        remaining_amount:
          type: string
          description: Amount (nominal) of the asset remaining to be liquidated
          example: '0.05'
        remaining_notional:
          type: string
          description: USD notional value of the remaining amount
          example: '5726.59'
    coinbase.public_rest_api.XMRiskNettingInfo:
      type: object
      properties:
        dco_margin_requirement:
          type: string
          description: >-
            Derivatives Clearing Organization Margin Requirement (DMR) is the
            margin requirement for all futures positions, derived from the
            Derivatives Clearing Organization model
          example: '9243.25'
        portfolio_margin_requirement:
          type: string
          description: >-
            Portfolio Margin Requirement (PMR) is the margin requirement for all
            spot positions, derived from the XM model
          example: '9003.67'
        integrated_portfolio_margin_requirement:
          type: string
          description: >-
            Integrated Portfolio Margin Requirement (IPMR) is the margin
            requirement for all spot positions + futures positions with
            underlying assets eligible in Portfolio Margin, via the XM model
            with one-leg netting
          example: '10154.67'
        ineligible_futures_margin_requirement:
          type: string
          description: >-
            Ineligible Futures Margin Requirement (IFMR) is the margin
            requirement for IPMR-ineligible futures contracts
          example: '194.36'
        position_margin_requirement:
          type: string
          description: Position margin requirement for all spot positions
          example: '3376.45'
        portfolio_margin_addon:
          type: string
          description: Portfolio margin addon for all spot positions
          example: '5627.21'
        integrated_position_margin_requirement:
          type: string
          description: Position margin requirement for spot + futures positions
          example: '3376.45'
        integrated_portfolio_margin_addon:
          type: string
          description: Portfolio margin addon for spot + futures positions
          example: '6778.21'
        netted_futures_notional:
          type: string
          description: Post-netting USD notional for all futures positions
          example: '11510.00'
        total_gmv_basis:
          type: string
          description: >-
            Total basis gross market value of all XM-eligible positions (i.e.
            crypto underliers)
        ipm_cash_balance:
          type: string
          description: Integrated Portfolio Margin cash balance
          example: '1002.94'
        integrated_scenario_addon:
          $ref: '#/components/schemas/coinbase.public_rest_api.MarginAddOn'
        all_integrated_scenario_addons:
          type: array
          description: All integrated scenario add-ons
          items:
            $ref: '#/components/schemas/coinbase.public_rest_api.MarginAddOn'
        xm_positions:
          type: array
          description: Netted positions used in the model calculation
          items:
            $ref: '#/components/schemas/coinbase.public_rest_api.XMPosition'
    coinbase.public_rest_api.MarginAddOn:
      type: object
      properties:
        amount:
          type: string
          description: margin add on amount
        add_on_type:
          $ref: '#/components/schemas/coinbase.public_rest_api.MarginAddOnType'
    coinbase.public_rest_api.XMPosition:
      title: XMPosition
      type: object
      properties:
        currency:
          type: string
          description: Position currency
          example: BTC
        market_price:
          type: string
          description: Current market price
          example: '114531.73'
        margin_eligible:
          type: boolean
          description: True if margin eligible, false otherwise
          example: true
        market_cap:
          type: string
          description: Total market capitalization
          example: '770000000000.00'
        adv30_days:
          type: string
          description: Average daily volume calculated over a 30-day period
          example: '1166623585.534257'
        hist5d_vol:
          type: string
          description: Historic volatility calculated over a 5-day period
          example: '0.010996074377389616'
        hist30d_vol:
          type: string
          description: Historic volatility calculated over a 30-day period
          example: '0.013617999336643158'
        hist90d_vol:
          type: string
          description: Historic volatility calculated over a 90-day period
          example: '0.015196480084775355'
        margin_requirement:
          type: string
          description: Base margin requirement for the specific asset
          example: '0.015'
        spot_balance:
          type: string
          description: XM spot balance nominal
          example: '-0.19652944'
        spot_balance_notional:
          type: string
          description: XM spot balance notional
          example: '-22508.85'
        spot_total_position_margin:
          type: string
          description: Pre-netted spot total position margin
        futures_balance:
          type: string
          description: XM futures balance nominal
          example: '-0.19652944'
        futures_balance_notional:
          type: string
          description: XM futures balance notional
          example: '-22508.85'
        futures_total_position_margin:
          type: string
          description: Pre-netted futures total position margin
        gmv_basis:
          type: string
          description: Basis GMV = |futures| + |spot| - |unnetted position|
        base_requirement:
          type: string
          description: Base margin requirement notional
        liq_shorts_add_on:
          type: string
          description: Effective liquidity add-on for the short positions
        liq_longs_add_on:
          type: string
          description: Effective liquidity add-on for the long positions
        vol_shorts_add_on:
          type: string
          description: Effective volatility add-on for the short positions
        vol_longs_add_on:
          type: string
          description: Effective volatility add-on for the long positions
        vol5days_add_on:
          type: string
          description: 5-day volatility add-on
        vol30days_add_on:
          type: string
          description: 30-day volatility add-on
        vol90days_add_on:
          type: string
          description: 90-day volatility add-on
        total_position_margin:
          type: string
          description: Total margin required
    coinbase.public_rest_api.MarginAddOnType:
      type: string
      default: MARGIN_ADD_ON_TYPE_UNSPECIFIED
      enum:
        - MARGIN_ADD_ON_TYPE_UNSPECIFIED
        - SINGLE_COIN_STRESS
        - CONCENTRATION_STRESS
        - MACRO_STRESS
        - SHORT_BIASED_STRESS

````