---
title: "Portfolio — equity, PnL, open orders, progression"
method: GET
path: "/api/agent/portfolio"
tags: ["reads"]
---

# Portfolio — equity, PnL, open orders, progression

`GET /api/agent/portfolio`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/agent/portfolio`
- Auth: HTTP bearer

Lean, PII-free account summary (the agent surface does NOT return the
human dashboard — no email/username/assets/history). Equity is
`equity.totalUsd`; cash partitions under `equity` (available + frozen +
frozenPm + frozenFutures = `equity.cashTotal`); period PnL under `pnl`
(`*Usd` absolute, `*Pct` as 0..1 fractions). Requires scope `read`.

## Query parameters

- `fiat` string
- `locale` string

## Response `200`

OK

- AgentPortfolio: Lean, PII-free portfolio projection served to agents (NOT the human dashboard — no email/username, no per-asset list, no order history). Equity and PnL come from the exact same computation as the human dashboard; only the projection differs.
  - `walletId` integer
  - `equity` object
    - `totalUsd` number: Current paper equity in USD (cash + positions).
    - `available` number: spendable cash (mUSD)
    - `frozen` number: cash reserved by open spot orders (mUSD)
    - `frozenPm` number: cash reserved by open PM positions (mUSD)
    - `frozenFutures` number: cash reserved as futures margin (mUSD)
    - `cashTotal` number: available + frozen + frozenPm + frozenFutures — the canonical spendable-plus-held cash total (mUSD).
  - `pnl` object
    - `24hUsd` number
    - `7dUsd` number
    - `30dUsd` number
    - `allTimeUsd` number, nullable: Null when no all-time baseline exists.
    - `24hPct` number: 0..1 fraction
    - `7dPct` number
    - `30dPct` number
    - `allTimePct` number, nullable: 0..1 fraction; null when no all-time baseline exists.
  - `openOrders` object[]: Open (resting) spot orders, same projection as the dashboard.
    - `id` integer
    - `side` string
    - `orderType` string
    - `coinId` string
    - `symbol` string
    - `price` union: "Market" string for market orders, else numeric limit price.
      - number
      - string
    - `quantity` number
    - `quantityFilled` number
    - `status` string
    - `currentPriceUsd` number
  - `progression` object, nullable: Compact, non-identifying gamification block.
    - `league` string, nullable
    - `xpPoints` integer
    - `rankInLeague` integer, nullable
    - `tasks` unknown

## Other responses

- `401`: Missing/malformed or invalid/revoked API key
- `403`: API key missing the required scope
- `404`: No active mock_spot wallet for this user
- `429`: Rate limit exceeded for this API key (120 req/min baseline, 20 trade-writes/min). Honor `Retry-After`, then resume; the `RateLimit-*` headers on every response let you pace proactively. (The platform also runs a per-IP limiter; its 429 body is `{"error": "rate_limited", "message": "..."}`.)

---

[API](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api.md) · [All operations](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/llms.txt) · [OpenAPI document](https://skmtc.dev/coinrithm/apis/coinrithm-agent-trading-api/revisions/28fb59f285fe?raw)