Position

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/alpaca/json-schema/alpaca-position-schema.json",
  "title": "Position",
  "description": "The positions API provides information about an account's current open positions. The response will include information such as cost basis, shares traded, and market value, which will be updated live as price information is updated. Once a position is closed, it will no longer be queryable through this API.",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/alpaca-us-trading-api-openapi.yml#/components/schemas/Position",
  "properties": {
    "asset_class": {
      "$ref": "#/$defs/AssetClass"
    },
    "asset_id": {
      "description": "Asset ID (For options this represents the option contract ID)",
      "format": "uuid",
      "type": "string"
    },
    "asset_marginable": {
      "type": "boolean"
    },
    "avg_entry_price": {
      "description": "Average entry price of the position",
      "minLength": 1,
      "type": "string"
    },
    "avg_entry_swap_rate": {
      "description": "The weighted-average exchange rate at the time the position was entered.",
      "format": "decimal",
      "type": "string"
    },
    "change_today": {
      "description": "Percent change from last day price (by a factor of 1)",
      "minLength": 1,
      "type": "string"
    },
    "cost_basis": {
      "description": "Total cost basis in dollar",
      "minLength": 1,
      "type": "string"
    },
    "current_price": {
      "description": "Current asset price per share",
      "minLength": 1,
      "type": "string"
    },
    "exchange": {
      "$ref": "#/$defs/ExchangeForPosition"
    },
    "lastday_price": {
      "description": "Last day's asset price per share based on the closing value of the last trading day",
      "minLength": 1,
      "type": "string"
    },
    "market_value": {
      "description": "Total dollar amount of the position",
      "minLength": 1,
      "type": "string"
    },
    "prev_swap_rate": {
      "description": "The exchange rate as of the previous close (i.e. yesterday's rate)",
      "format": "decimal",
      "type": "string"
    },
    "qty": {
      "description": "The number of shares",
      "minLength": 1,
      "type": "string"
    },
    "qty_available": {
      "description": "Total number of shares available minus open orders / locked for options covered call",
      "minLength": 1,
      "type": "string"
    },
    "side": {
      "description": "long",
      "enum": [
        "long",
        "short"
      ],
      "type": "string"
    },
    "swap_rate": {
      "description": "The current exchange rate (without mark-up) used to convert local-currency position values into USD. Present only for LCT (Local Currency Trading) accounts",
      "format": "decimal",
      "type": "string"
    },
    "symbol": {
      "description": "Symbol name of the asset",
      "type": "string"
    },
    "unrealized_intraday_pl": {
      "description": "Unrealized profit/loss in dollars for the day",
      "minLength": 1,
      "type": "string"
    },
    "unrealized_intraday_plpc": {
      "description": "Unrealized profit/loss percent (by a factor of 1)",
      "minLength": 1,
      "type": "string"
    },
    "unrealized_pl": {
      "description": "Unrealized profit/loss in dollars",
      "minLength": 1,
      "type": "string"
    },
    "unrealized_plpc": {
      "description": "Unrealized profit/loss percent (by a factor of 1)",
      "minLength": 1,
      "type": "string"
    },
    "usd": {
      "$ref": "#/$defs/USDPositionValues"
    }
  },
  "required": [
    "asset_id",
    "symbol",
    "exchange",
    "asset_class",
    "avg_entry_price",
    "qty",
    "side",
    "market_value",
    "cost_basis",
    "unrealized_pl",
    "unrealized_plpc",
    "unrealized_intraday_pl",
    "unrealized_intraday_plpc",
    "current_price",
    "lastday_price",
    "change_today",
    "asset_marginable"
  ],
  "type": "object",
  "$defs": {
    "AssetClass": {
      "description": "This represents the category to which the asset belongs to. It serves to identify the nature of the financial instrument, with options including \"us_equity\" for U.S. equities, \"us_option\" for U.S. options, \"crypto\" for cryptocurrencies, and \"ipo\" for IPO indications of interest/orders. This `asset_class: ipo` value is distinct from the assets API `attributes: [\"ipo\"]` flag.",
      "enum": [
        "us_equity",
        "us_option",
        "crypto",
        "crypto_perp",
        "treasury",
        "corporate",
        "global_equity",
        "us_index",
        "us_equity_chain",
        "ipo"
      ],
      "title": "AssetClass",
      "type": "string"
    },
    "ExchangeForPosition": {
      "description": "Represents the current exchanges Alpaca supports. List is currently:\n\nUS equities:\n- AMEX\n- ARCA\n- BATS\n- NYSE\n- NASDAQ\n- NYSEARCA\n- OTC\n- TXSE\n\nCrypto:\n- CRYPTO\n- ERSX\n- CRXL\n\nCrypto perpetuals:\n- ASCX\n\nIndex symbols:\n- INDEX\n\nINDEX is the artificial exchange for index symbols such as SPX.\n\nCan be empty if not applicable (e.g., for options contracts)",
      "enum": [
        "AMEX",
        "ARCA",
        "BATS",
        "NYSE",
        "NASDAQ",
        "NYSEARCA",
        "OTC",
        "CRYPTO",
        "TXSE",
        "ERSX",
        "CRXL",
        "ASCX",
        "INDEX",
        ""
      ],
      "title": "Exchange",
      "type": "string"
    },
    "USDPositionValues": {
      "description": "Position values in USD. This is returned for LCT (non-USD) accounts only.",
      "properties": {
        "avg_entry_price": {
          "description": "Average entry price of the position in USD",
          "format": "decimal",
          "type": "string"
        },
        "change_today": {
          "description": "Percent change from last day price (by a factor of 1)",
          "format": "decimal",
          "type": "string"
        },
        "cost_basis": {
          "description": "Total cost basis in USD",
          "format": "decimal",
          "type": "string"
        },
        "current_price": {
          "description": "Current asset price per share in USD",
          "format": "decimal",
          "type": "string"
        },
        "lastday_price": {
          "description": "Last day's asset price per share based on the closing value of the last trading day in USD",
          "format": "decimal",
          "type": "string"
        },
        "market_value": {
          "description": "Total market value of the position in USD",
          "format": "decimal",
          "type": "string"
        },
        "unrealized_intraday_pl": {
          "description": "Unrealized profit/loss in USD for the day",
          "format": "decimal",
          "type": "string"
        },
        "unrealized_intraday_plpc": {
          "description": "Unrealized intraday profit/loss percent (by a factor of 1)",
          "format": "decimal",
          "type": "string"
        },
        "unrealized_pl": {
          "description": "Unrealized profit/loss in USD",
          "format": "decimal",
          "type": "string"
        },
        "unrealized_plpc": {
          "description": "Unrealized profit/loss percent (by a factor of 1)",
          "format": "decimal",
          "type": "string"
        }
      },
      "required": [
        "avg_entry_price",
        "cost_basis"
      ],
      "title": "USDPositionValues",
      "type": "object"
    }
  }
}