--- title: "GetPortfolio" method: POST path: "/portfolio.v1.PortfolioService/GetPortfolio" tags: ["Portfolio"] --- # GetPortfolio `POST /portfolio.v1.PortfolioService/GetPortfolio` Returns an aggregated portfolio snapshot for one wallet: margin, PnL, volume, fee, and equity totals, plus the wallet's currently open positions and open orders. NOTE: `positions` and `orders` are open-only — closed positions and terminal-status orders are folded into the aggregate totals but are not listed individually here. All totals are recomputed fresh on every request (not cached), so this endpoint is heavier than a single-position or single-order lookup. ## Headers - `Connect-Protocol-Version` 1, required — Define the version of the Connect protocol. If omitted, use 1. - `Connect-Timeout-Ms` number — Define the timeout, in ms ## Request body - PortfolioV1GetPortfolioRequest - `owner` string, required — Wallet address to compute a portfolio for. ## Response `200` Success - PortfolioV1GetPortfolioResponse - `portfolio` BaseObjectsV1Portfolio - `owner` string — Wallet address this portfolio was computed for. - `timestamp` string, date-time - `totalMargin` number, float — Sum of allocated margin across open positions only, in USD. - `totalUnrealizedPnl` number, float — Sum of unrealized PnL across open positions only, in USD. Per position: `(markPrice - entryPrice) * size` for longs, `(entryPrice - markPrice) * size` for shorts. Recomputed on every request from live prices. - `totalRealizedPnl` number, float — Realized PnL from closed positions, net of fees: `totalProfit - totalLoss - totalFees`. - `totalVolume` number, float — Cumulative notional value of all trades (entries and exits) in USD, across both open and closed positions. - `totalFees` number, float — Cumulative fees paid across all trades, in USD. The underlying fee-structure calculation is still evolving server-side. - `totalProfit` number, float — Sum of gross profits from closed positions, excluding fees, in USD. - `totalLoss` number, float — Sum of gross losses from closed positions (including liquidations), excluding fees, in USD. Always a positive value. - `totalTrades` string, int64 — Count of fill-type order events (full fills, partial fills, and merges) across the wallet's order history. - `totalEquity` number, float — Current total portfolio value: `totalMargin + totalUnrealizedPnl`. - `maxDrawdown` number, float — Maximum observed decline in portfolio equity from any peak to a subsequent trough - `positions` BaseObjectsV1Position[] — Open positions only. Closed positions are excluded. They're only reflected in the aggregate totals above, not in this list). - `owner` string — Lowercase EVM wallet address that owns the position. - `positionId` string, int64 — On-chain position identifier. The same ID as the order that opened the position. - `marketId` string, int64 — On-chain market identifier. - `timestamp` string, date-time - `market` string — Human-readable market name, such as `BTC-PERP`. - `side` 'SIDE_LONG' | 'SIDE_SHORT' — Direction of the position represented by an order. - `marginType` 'MARGIN_TYPE_ISOLATED' - `nominalSize` number, float — Position size in the base asset's units. - `entryPrice` number, float — Average entry price in quote asset units. - `markPrice` number, float — Current mark price in quote asset units. - `liquidationPrice` number, float — Estimated liquidation price in quote asset units. Not a stored on-chain value. - `allocatedMargin` number, float — Current collateral allocated to the position, in quote asset units, including any margin adds or removes since the position opened. - `leverage` number, float — Leverage multiplier used to open the position. - `unrealizedPnl` number, float — Unrealized profit or loss in quote asset units, derived from `markPrice` vs. `entryPrice`. Recomputed on every read, not a stored value. - `reduceOnly` boolean — Legacy field mirrored from the position's on-chain open/update events. Not generally meaningful at the position level — see `associatedOrders` for the position's individual reduce-only orders. - `associatedOrders` BaseObjectsV1Order[] — Orders associated with this position (opening and reduce-only). - `owner` string — Lowercase EVM wallet address that owns the order. - `orderId` string, int64 — On-chain order identifier. Unique together with `marketId` and `reduceOnly`. Connect/JSON encodes this uint64 as a decimal string. - `timestamp` string, date-time - `marketId` string, int64 — On-chain market identifier. Connect/JSON encodes this uint64 as a decimal string. - `market` string — Human-readable market name, such as `BTC-PERP`. Falls back to `MARKET-{marketId}` when market metadata is unavailable. - `type` 'ORDER_TYPE_MARKET' — Order-type classification used by the API. Currently only market orders are returned. - `side` 'SIDE_LONG' | 'SIDE_SHORT' — Direction of the position represented by an order. - `thresholdPrice` number, float — Execution price threshold in quote asset terms per underlying asset. Converted using the market's tick precision. This is not necessarily the fill price. - `size` number, float — Amount exposed for the order. - `leverage` number, float — Leverage multiplier. For reduce-only orders, inherited from the associated position-opening order when available. - `status` 'ORDER_STATUS_PENDING' | 'ORDER_STATUS_PARTIALLY_FILLED' | 'ORDER_STATUS_FULLY_FILLED' | 'ORDER_STATUS_CLOSED' | 'ORDER_STATUS_CANCELLED' | 'ORDER_STATUS_MERGED' | 'ORDER_STATUS_PARTIALLY_MERGED' | 'ORDER_STATUS_PARTIALLY_CANCELLED' — Current lifecycle state of an order. - `filledSize` number, float — Order Amount that has been filled - `unfilledSize` number, float — Order amount remaining to be filled - `reduceOnly` boolean — Whether the order is reducing an existing position. False for orders that open or increase exposure; true for orders that reduce exposure. - `canceled` boolean — Legacy field that the server does not populate. Use `status` to determine whether an order was cancelled. - `initialMargin` number, float — Initial collateral or threshold-price notional, denominated in quote asset units. For position-opening orders, this is the initial collateral. - `tickDecimals` integer — Market price precision used to convert raw on-chain price values. - `fees` number, float — Fees recorded for the order, denominated in quote asset units. - `rebates` number, float — Direct order-side rebates recorded for reduce fills, denominated in quote asset units. - `reduceOrderType` string — Reduce-order classification. Values are `MANUAL`, `STOP_LOSS`, `TAKE_PROFIT`, `LIQUIDATION`, or `ADL`. Empty for position-opening orders. - `initialNotional` number, float — Initial notional amount for a position-opening order. Calculated as `initialMargin * leverage`. Zero for reduce-only orders. - `stopLossPrice` number, float — Stop-loss trigger price attached to a position-opening order, in quote asset units. Zero when no stop-loss is configured. - `takeProfitPrice` number, float — Take-profit trigger price attached to a position-opening order, in quote asset units. Zero when no take-profit is configured. - `associatedOrderIds` BaseObjectsV1OrderRef[] — Lightweight identifiers for orders associated with this position. - `orderId` union — On-chain order identifier. Combine with `marketId` and `reduceOnly` to look up the full order via `GetOrder`. - integer - string, int64 - `marketId` union — Market the referenced order belongs to. - integer - string, int64 - `reduceOnly` boolean — Whether the referenced order is reduce-only. - `tickDecimals` integer — Market price precision used to convert raw on-chain price values. - `revenueSpent` number, float — Revenue-per-unit snapshot recorded when the position opened. The position's total earned revenue at close time is `market_revenue - revenue_spent`. - `effectiveSize` number, float — Currently always equal to `nominalSize`. Intended to eventually scale by an ADL scale factor (`position.adl_scale_factor / market.adl_scale_factor`), but that scaling is not yet implemented server-side. - `estimatedRebate` number, float — Estimated rebate accrued to this position so far, in quote asset units — the market's current cumulative revenue-per-unit for this position's side, minus `revenueSpent`. Returns `0` if the underlying revenue data isn't available yet, or `-1` if the market itself can't be loaded. - `stopLossPrice` number, float — Stop-loss trigger price derived from this position's active reduce orders, in quote asset units. Zero when no stop-loss is configured - `takeProfitPrice` number, float — Take-profit trigger price derived from this position's active reduce orders, in quote asset units. Zero when no take-profit is configured - `orders` BaseObjectsV1Order[] — Open orders only. Filled, cancelled, and other terminal-status orders are excluded. - `owner` string — Lowercase EVM wallet address that owns the order. - `orderId` string, int64 — On-chain order identifier. Unique together with `marketId` and `reduceOnly`. Connect/JSON encodes this uint64 as a decimal string. - `timestamp` string, date-time - `marketId` string, int64 — On-chain market identifier. Connect/JSON encodes this uint64 as a decimal string. - `market` string — Human-readable market name, such as `BTC-PERP`. Falls back to `MARKET-{marketId}` when market metadata is unavailable. - `type` 'ORDER_TYPE_MARKET' — Order-type classification used by the API. Currently only market orders are returned. - `side` 'SIDE_LONG' | 'SIDE_SHORT' — Direction of the position represented by an order. - `thresholdPrice` number, float — Execution price threshold in quote asset terms per underlying asset. Converted using the market's tick precision. This is not necessarily the fill price. - `size` number, float — Amount exposed for the order. - `leverage` number, float — Leverage multiplier. For reduce-only orders, inherited from the associated position-opening order when available. - `status` 'ORDER_STATUS_PENDING' | 'ORDER_STATUS_PARTIALLY_FILLED' | 'ORDER_STATUS_FULLY_FILLED' | 'ORDER_STATUS_CLOSED' | 'ORDER_STATUS_CANCELLED' | 'ORDER_STATUS_MERGED' | 'ORDER_STATUS_PARTIALLY_MERGED' | 'ORDER_STATUS_PARTIALLY_CANCELLED' — Current lifecycle state of an order. - `filledSize` number, float — Order Amount that has been filled - `unfilledSize` number, float — Order amount remaining to be filled - `reduceOnly` boolean — Whether the order is reducing an existing position. False for orders that open or increase exposure; true for orders that reduce exposure. - `canceled` boolean — Legacy field that the server does not populate. Use `status` to determine whether an order was cancelled. - `initialMargin` number, float — Initial collateral or threshold-price notional, denominated in quote asset units. For position-opening orders, this is the initial collateral. - `tickDecimals` integer — Market price precision used to convert raw on-chain price values. - `fees` number, float — Fees recorded for the order, denominated in quote asset units. - `rebates` number, float — Direct order-side rebates recorded for reduce fills, denominated in quote asset units. - `reduceOrderType` string — Reduce-order classification. Values are `MANUAL`, `STOP_LOSS`, `TAKE_PROFIT`, `LIQUIDATION`, or `ADL`. Empty for position-opening orders. - `initialNotional` number, float — Initial notional amount for a position-opening order. Calculated as `initialMargin * leverage`. Zero for reduce-only orders. - `stopLossPrice` number, float — Stop-loss trigger price attached to a position-opening order, in quote asset units. Zero when no stop-loss is configured. - `takeProfitPrice` number, float — Take-profit trigger price attached to a position-opening order, in quote asset units. Zero when no take-profit is configured. --- [API](https://skmtc.dev/fairground/apis/fairground-fi-api.md) · [All operations](https://skmtc.dev/fairground/apis/fairground-fi-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fairground/fairground-fi-api/revisions/be66e6dc0ac0/schema)