---
title: "Get the authenticated user's portfolio"
url: https://docs.truemarkets.co/api/gateway/get-portfolio
description: "Unified portfolio across CeFi and DeFi venues: valued balances, open positions, and PnL in a single call."
---

Docs index: https://docs.truemarkets.co/llms.txt

# Get the authenticated user's portfolio

Unified portfolio across CeFi and DeFi venues: valued balances, open positions, and PnL in a single call.

`total_usd` is total account equity: `balances_usd` plus the margin committed to open positions, counted once. A Hyperliquid unified account's spot USDC balance already holds that margin, so none is added for it. Unrealized PnL is deliberately not added, because balances and margin are already marked to market. `balances_usd` on its own is the value of balances, which excludes collateral committed to perps except on a unified account.

A balance with no live price returns `price`, `value` and `change_24h_pct` as null and is excluded from every total. A CeFi holding that TrueX or the asset catalog cannot identify has no row, counts in no total and is named in `incomplete.unrecognized_cefi_assets`.

Funds allocated to CeFi trading count once, through the CeFi row: a DeFi row's `allocated` quantity is left out of its `value` and of DeFi's totals. Funds allocated that TrueX has not credited yet appear as the CeFi row's `in_transit` and count in the totals at that row's price. A release needs no such add-back, since TrueX completes its debit only once the allocation is released.

`cost_basis` is present only for non-quote assets acquired on platform. Quote and stable assets omit it, and so does any quantity received by deposit or bridge.

A read that fails is flagged in `incomplete` rather than failing the request. When DeFi, TrueX or pricing cannot be read, the venues that were read are still returned, `incomplete.defi_unavailable` or `incomplete.cefi_unavailable` is set, and every aggregate (`total_usd`, `account_total_usd`, `balances_usd`, `cash_usd`, `change_24h_usd`, `change_24h_pct`, `unrealized_pnl_usd`, `realized_pnl_usd`) is null: each depends on both venues, so a partial sum would be wrong rather than merely incomplete.

`total_usd` covers the main wallet only. The Strategies wallet is a separate account, reported in `strategies` and added into `account_total_usd`; it is read only when no `venue` filter is set. A failed Strategies read returns `strategies` and `account_total_usd` as null and sets `incomplete.strategies_unavailable`, and the request still succeeds.

## Request

```
GET https://api.truemarkets.co/v1/gateway/portfolio
```

### Authentication

Bearer token in `Authorization`

### Parameters

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `TM-On-Behalf-Of` | header | string (uuid) | no | Act as one of your organization's users. The value is the `user_id` returned when the user was created; the request then reads and writes that user's account. Requires an organization token and a user your organization created: `400` for a personal token, a repeated header or a non-UUID, `403` for a user outside your organization. Not accepted on organization-scoped routes. |
| `venue` | query | string, one of `defi`, `cefi` | no | Restrict the portfolio to one venue (`defi`, `cefi`). Defaults to all venues when omitted. |

## Responses

Every error status returns the same body, described in [Errors](https://docs.truemarkets.co/developer-resources/errors.md).

### 200

The user's portfolio

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `total_usd` | string, nullable | yes | Main wallet account equity (decimal string): balances_usd plus the margin committed to open positions, counted once. A Hyperliquid unified account's spot USDC balance already holds that margin, so none is added for it. Unrealized PnL is not added; balances and margin are already marked to market. The Strategies wallet is not included; see account_total_usd. Null when a venue in scope could not be read (incomplete.defi_unavailable or incomplete.cefi_unavailable). |
| `account_total_usd` | string, nullable | yes | total_usd plus strategies.value_usd (decimal string): both wallets. Null whenever either is unknown: when total_usd is null, when the Strategies read failed, when strategies.perp_data_unavailable is true, or when a venue filter is set. |
| `balances_usd` | string, nullable | yes | Value of balances (decimal string), excluding unpriced assets. Collateral committed to open perps is excluded, except on a Hyperliquid unified account, whose spot USDC balance holds it. Null when a venue in scope could not be read. |
| `cash_usd` | string, nullable | yes | Value of stablecoin and quote-asset balances at the venues in scope (decimal string). Null when a venue in scope could not be read. |
| `change_24h_usd` | string, nullable | yes | Rolling 24h change in balance value (decimal string). Null when a venue in scope could not be read. |
| `change_24h_pct` | string, nullable | yes | Rolling 24h change as a percent (decimal string). Null when a venue in scope could not be read. |
| `unrealized_pnl_usd` | string, nullable | yes | Spot unrealized PnL plus position unrealized PnL (decimal string). Spot covers on-platform acquisitions only. Null when a venue in scope could not be read. |
| `realized_pnl_usd` | string, nullable | yes | Realized PnL from on-platform spot sells (decimal string). Null when a venue in scope could not be read. |
| `balances` | array of object | yes |  |
| `balances[].asset_id` | string (uuid) | no | Unique asset identifier; pass as `asset_id` when creating an order. Absent when the asset is not in the catalog. |
| `balances[].economic_asset_id` | string (uuid) | no | Economic asset this listing belongs to, shared across venues and chains. Absent when the asset is not in the catalog. |
| `balances[].symbol` | string | yes | Asset ticker symbol (e.g. BTC, USDC) |
| `balances[].name` | string | no | Human-readable asset name |
| `balances[].venue` | string, one of `defi`, `cefi` | yes | The trading venue to filter by. * **defi** — Decentralized exchange (on-chain swaps). * **cefi** — Centralized exchange (off-chain order book). |
| `balances[].chain` | string, nullable | no | Blockchain network, or null for exchange-held assets |
| `balances[].address` | string, nullable | no | Token contract/mint address, or null for exchange-held assets |
| `balances[].decimals` | integer | yes | Display precision |
| `balances[].icon` | string, nullable | no | Icon image URL |
| `balances[].status` | string, one of `active`, `preview`, `sell_only`, `transfer_only`, `disabled` | no | Per-listing trading status |
| `balances[].stable` | boolean | yes | Whether this is a stablecoin |
| `balances[].tradeable` | boolean | yes | Whether this asset is active for trading |
| `balances[].total` | string | yes | Gross balance including held amounts (decimal string) |
| `balances[].available` | string | yes | Usable balance after holds (decimal string) |
| `balances[].held` | string | yes | Amount locked in orders or transfers (decimal string) |
| `balances[].allocated` | string | no | DeFi rows only: the quantity of total committed to CeFi trading (decimal string). The CeFi row holds it, so value and the totals leave it out. Absent when the DeFi service does not report it. |
| `balances[].in_transit` | string | no | CeFi rows only: quantity allocated to CeFi trading that TrueX has not yet credited, read against TrueX's own transfer status (decimal string). It counts in the totals at this row's price but not in value. Absent when nothing is in transit. Between DeFi applying a release and TrueX completing its debit, both sides briefly hold the released amount; conductor cannot observe that window. |
| `balances[].price` | string, nullable | no | Current USD price per unit; null when unpriced |
| `balances[].value` | string, nullable | no | USD value of total, less allocated on a DeFi row; null when unpriced and excluded from totals |
| `balances[].change_24h_pct` | string, nullable | no | Rolling 24h price change as a percent (decimal string) |
| `balances[].cost_basis` | object | no | On-platform cost basis for one asset symbol, FIFO over buys. Absent for quote and stable assets and when the holding was acquired entirely off platform. |
| `balances[].cost_basis.avg_entry_price` | string | yes | FIFO average entry price of the still-held on-platform quantity |
| `balances[].cost_basis.cost_usd` | string | yes | USD cost of the still-held on-platform quantity |
| `balances[].cost_basis.qty` | string | yes | Still-held quantity acquired on platform, clamped so it never exceeds the row's total. |
| `balances[].cost_basis.realized_pnl` | string | yes | Realized PnL from sells; sell fees reduce proceeds |
| `balances[].cost_basis.unrealized_pnl` | string | yes | Mark-to-market PnL on the still-held on-platform quantity |
| `positions` | array of object | yes |  |
| `positions[].asset_id` | string (uuid) | no | Unique asset identifier for the perp; pass as `asset_id` when creating an order. Empty when the coin is not listed. |
| `positions[].venue` | string, one of `defi`, `cefi` | no | The trading venue to filter by. * **defi** — Decentralized exchange (on-chain swaps). * **cefi** — Centralized exchange (off-chain order book). |
| `positions[].symbol` | string | no | Asset ticker symbol (e.g. BTC) |
| `positions[].side` | string, one of `long`, `short` | no | Position direction |
| `positions[].size` | string | no | Absolute position size in the base asset (decimal string) |
| `positions[].entry_price` | string | no | Average entry price (decimal string) |
| `positions[].mark_price` | string | no | Current mark price used to value the position (decimal string) |
| `positions[].liquidation_price` | string, nullable | no | Estimated liquidation price, or null when none is reported |
| `positions[].margin_used` | string | no | Margin committed to this position (decimal string) |
| `positions[].unrealized_pnl` | string | no | Signed unrealized PnL at mark (decimal string). Reported but never added into a portfolio total; balances and margin are already marked to market. |
| `positions[].return_on_equity` | string | no | Unrealized PnL as a fraction of margin used (decimal string) |
| `positions[].leverage` | integer | no | Configured leverage for the position |
| `strategies` | object, nullable | yes | The Strategies wallet. Null when a venue filter is set or when the Strategies read failed, in which case incomplete.strategies_unavailable is true. |
| `strategies.value_usd` | string, nullable | yes | Value of the whole Strategies wallet (decimal string). Null when perp_data_unavailable is true. |
| `strategies.cash_usd` | string | yes | Stablecoin cash in the Strategies wallet (decimal string) |
| `strategies.free_usd` | string, nullable | yes | Cash not allocated to any strategy (decimal string). Null when perp_data_unavailable is true. |
| `strategies.allocated_usd` | string | yes | Capital allocated across the user's strategies (decimal string) |
| `strategies.pnl_usd` | string, nullable | yes | Total P&L across the user's strategies (decimal string). Null when perp_data_unavailable is true. |
| `strategies.pnl_24h_usd` | string, nullable | yes | P&L across the user's strategies over the last 24 hours (decimal string), measured against each strategy's P&L snapshot from then; money moved in or out is not P&L. Null when perp_data_unavailable is true or a strategy has no snapshot from then. |
| `strategies.as_of` | string (date-time) | yes | When the strategy service took the snapshot these figures come from |
| `strategies.perp_data_unavailable` | boolean | yes | True when the perp venue could not be read, so the figures that depend on it are null rather than wrong. |
| `incomplete` | object | no | What the portfolio could not read or value exactly. Omitted when everything was read. Every field is omitted when it has nothing to report. |
| `incomplete.unavailable_chains` | array of object | no | DeFi chain reads that failed. Their balances are missing from the rows and totals. |
| `incomplete.unavailable_chains[].chain` | string | yes | The chain whose read failed |
| `incomplete.unavailable_chains[].owner` | string | yes | The wallet the failed read belonged to, as DeFi names it |
| `incomplete.unpriced` | array of string | no | Symbols of non-stable holdings, on either venue, with no live price. They are excluded from every total. |
| `incomplete.over_allocated` | array of object | no | DeFi listings whose CeFi allocation exceeds the on-chain total. The DeFi row counts none of it. |
| `incomplete.over_allocated[].asset_id` | string (uuid) | yes | DeFi listing id |
| `incomplete.over_allocated[].symbol` | string | yes | Asset ticker symbol |
| `incomplete.stranded` | array of object | no | DeFi listings with an allocation or release whose outcome is unknown and awaits an operator. Its amount is not counted as in transit, so the CeFi side may be off by it. |
| `incomplete.stranded[].asset_id` | string (uuid) | yes | DeFi listing id |
| `incomplete.stranded[].symbol` | string | yes | Asset ticker symbol |
| `incomplete.unrecognized_cefi_assets` | array of string | no | CeFi holdings TrueX reports that could not be identified: TrueX could not name the asset, or the asset catalog has no metadata for it. Each is the symbol when TrueX named it, otherwise the TrueX asset id. They have no row and are excluded from every total. |
| `incomplete.positions_unavailable` | boolean | no | True when DeFi could not read the perp positions; positions is then empty. |
| `incomplete.defi_unavailable` | boolean | no | True when the DeFi portfolio could not be read. No DeFi rows or positions are returned and every aggregate is null. |
| `incomplete.cefi_unavailable` | boolean | no | True when the CeFi balances, their prices or the status of a CeFi credit in flight could not be read. No CeFi rows are returned and every aggregate is null. |
| `incomplete.strategies_unavailable` | boolean | no | True when the Strategies wallet could not be read |

### 400

Bad request

### 401

Unauthorized

### 403

Forbidden. On order creation this also covers an asset that is not available to trade from the country the request came from.

### 500

Internal server error
