{
  "path": "/futures/{settle}/positions/{contract}",
  "operation_id": "getPosition",
  "auth_required": true,
  "parameters": [
    {
      "name": "settle",
      "in": "path",
      "description": "Perpetual futures settlement currency",
      "required": true,
      "schema": {
        "type": "string",
        "enum": [
          "btc",
          "usdt",
          "usd1"
        ]
      },
      "example": "usdt"
    },
    {
      "name": "contract",
      "in": "path",
      "description": "Futures contract",
      "required": true,
      "schema": {
        "type": "string"
      },
      "example": "BTC_USDT"
    }
  ],
  "response_fields": {
    "200": {
      "description": "Position information",
      "fields": [
        {
          "path": "$",
          "type": "object",
          "description": "Futures position details",
          "constraints": ""
        },
        {
          "path": "$.user",
          "type": "integer",
          "description": "User ID",
          "constraints": "格式：\"int64\""
        },
        {
          "path": "$.contract",
          "type": "string",
          "description": "Futures contract",
          "constraints": ""
        },
        {
          "path": "$.size",
          "type": "string",
          "description": "Position size",
          "constraints": ""
        },
        {
          "path": "$.hedge_status",
          "type": "string",
          "description": "The hedging status of the position under the Delta-neutral strategy. Including:\n\n- `partial_hedged`: partially hedged\n- `full_hedged`: fully hedged",
          "constraints": "枚举：partial_hedged / full_hedged"
        },
        {
          "path": "$.hedged_size",
          "type": "string",
          "description": "The hedged position size under the Delta-neutral strategy.",
          "constraints": ""
        },
        {
          "path": "$.unhedged_size",
          "type": "string",
          "description": "The unhedged position size under the Delta-neutral strategy, calculated as `max(abs(size) - abs(hedged_size), 0)`.",
          "constraints": ""
        },
        {
          "path": "$.leverage",
          "type": "string",
          "description": " leverage for isolated margin. 0 means cross margin. For leverage of cross margin, please refer to `cross_leverage_limit`.",
          "constraints": ""
        },
        {
          "path": "$.risk_limit",
          "type": "string",
          "description": "Position risk limit",
          "constraints": ""
        },
        {
          "path": "$.leverage_max",
          "type": "string",
          "description": "the maximum permissible leverage given to the current positon value: the higher positon value, the lower maximum permissible leverage",
          "constraints": ""
        },
        {
          "path": "$.maintenance_rate",
          "type": "string",
          "description": "The maintenance margin requirement for the risk limit at which the current position size is located.Since the maintenance margin for the position has been calculated using a tiered system, the actual maintenance margin rate required for this position is based on `average_maintenance_rate`.",
          "constraints": ""
        },
        {
          "path": "$.value",
          "type": "string",
          "description": "Position value calculated in settlement currency",
          "constraints": ""
        },
        {
          "path": "$.margin",
          "type": "string",
          "description": "Margin",
          "constraints": ""
        },
        {
          "path": "$.entry_price",
          "type": "string",
          "description": "Entry price",
          "constraints": ""
        },
        {
          "path": "$.liq_price",
          "type": "string",
          "description": "Estimated liquidation price, for reference only. The actual liquidation trigger is based on the position mmr or the account maintenance margin level.",
          "constraints": ""
        },
        {
          "path": "$.mark_price",
          "type": "string",
          "description": "Current mark price",
          "constraints": ""
        },
        {
          "path": "$.initial_margin",
          "type": "string",
          "description": "Initial margin of postions",
          "constraints": ""
        },
        {
          "path": "$.maintenance_margin",
          "type": "string",
          "description": "Maintencance margin of postions",
          "constraints": ""
        },
        {
          "path": "$.unrealised_pnl",
          "type": "string",
          "description": "Unrealized PNL",
          "constraints": ""
        },
        {
          "path": "$.realised_pnl",
          "type": "string",
          "description": "Realised PnL, the sum of all cash flows generated by this position, including settlement of closing positions, settlement of funding fees, and transaction fee expenses.",
          "constraints": ""
        },
        {
          "path": "$.pnl_pnl",
          "type": "string",
          "description": "settled pnl when closing postion",
          "constraints": ""
        },
        {
          "path": "$.pnl_fund",
          "type": "string",
          "description": "funding fees",
          "constraints": ""
        },
        {
          "path": "$.pnl_fee",
          "type": "string",
          "description": "trading fees",
          "constraints": ""
        },
        {
          "path": "$.history_pnl",
          "type": "string",
          "description": "Total realized PnL from closed positions",
          "constraints": ""
        },
        {
          "path": "$.last_close_pnl",
          "type": "string",
          "description": "PNL of last position close",
          "constraints": ""
        },
        {
          "path": "$.realised_point",
          "type": "string",
          "description": "Realized POINT PNL",
          "constraints": ""
        },
        {
          "path": "$.history_point",
          "type": "string",
          "description": "History realized POINT PNL",
          "constraints": ""
        },
        {
          "path": "$.adl_ranking",
          "type": "integer",
          "description": "Ranking of auto deleveraging, a total of 1-5 grades, `1` is the highest, `5` is the lowest, and `6` is the special case when there is no position held or in liquidation",
          "constraints": ""
        },
        {
          "path": "$.pending_orders",
          "type": "integer",
          "description": "Current pending order quantity",
          "constraints": ""
        },
        {
          "path": "$.close_order",
          "type": "object",
          "description": "Current close order information, or `null` if no close order",
          "constraints": ""
        },
        {
          "path": "$.close_order.id",
          "type": "integer",
          "description": "Order ID",
          "constraints": "格式：\"int64\""
        },
        {
          "path": "$.close_order.price",
          "type": "string",
          "description": "Order price",
          "constraints": ""
        },
        {
          "path": "$.close_order.is_liq",
          "type": "boolean",
          "description": "Whether the close order is from liquidation",
          "constraints": ""
        },
        {
          "path": "$.mode",
          "type": "string",
          "description": "Position mode, including:\n\n- `single`: One-way Mode\n- `dual_long`: Long position in Hedge Mode\n- `dual_short`: Short position in Hedge Mode",
          "constraints": "枚举：single / dual_long / dual_short"
        },
        {
          "path": "$.cross_leverage_limit",
          "type": "string",
          "description": "leverage for cross margin",
          "constraints": ""
        },
        {
          "path": "$.update_time",
          "type": "integer",
          "description": "Last update time",
          "constraints": "格式：\"int64\""
        },
        {
          "path": "$.update_id",
          "type": "integer",
          "description": "Update ID. The value increments by 1 each time the position is updated",
          "constraints": "格式：\"int64\""
        },
        {
          "path": "$.open_time",
          "type": "integer",
          "description": "First Open Time",
          "constraints": "格式：\"int64\""
        },
        {
          "path": "$.risk_limit_table",
          "type": "string",
          "description": "Risk limit table ID",
          "constraints": ""
        },
        {
          "path": "$.average_maintenance_rate",
          "type": "string",
          "description": "Average maintenance margin rate",
          "constraints": ""
        },
        {
          "path": "$.pid",
          "type": "integer",
          "description": "Sub-account position ID",
          "constraints": "格式：\"int64\""
        },
        {
          "path": "$.pos_margin_mode",
          "type": "string",
          "description": "Position Margin Mode isolated - Isolated Margin, cross - Cross Margin",
          "constraints": ""
        },
        {
          "path": "$.lever",
          "type": "string",
          "description": "Indicates the current leverage of the position, applicable to both isolated and cross margin, gradually replacing the current leverage and cross_leverage_limit",
          "constraints": ""
        }
      ]
    }
  },
  "source_version": "v4.106.132",
  "source_url": "https://github.com/gate/gateapi-python/blob/cd2cac4d339ec0734480787d23c020f467fd7b80/openapi.yaml",
  "local_tool_limits": [
    "仅检查必填、枚举和简单数值范围",
    "复杂类型序列化、条件必填、时间窗口等以官方规则为准",
    "不会发起 API 请求"
  ]
}