---
title: "List this key's pm_paper_v2 positions with exact accounting"
method: GET
path: "/api/agent/pm/v2/positions"
tags: ["prediction-markets"]
---

# List this key's pm_paper_v2 positions with exact accounting

`GET /api/agent/pm/v2/positions`

## Request

- Base URL: `https://api.coinrithm.com`
- URL: `https://api.coinrithm.com/api/agent/pm/v2/positions`
- Auth: HTTP bearer

Newest-first page of the calling key's `pm_paper_v2` positions (v1
positions stay on /api/agent/positions/pm), plus an unpaginated risk
summary, the key's house enrollment and whether entry is enabled.
Money and quantity are exact integer strings: `*Quanta6` values are
paper mUSD x 1,000,000 and `quantityUnits2` is shares x 100. Payout,
PnL and `terminal` stay null until the close or settlement is fully
recorded (`accountingStatus: settled`). Any key with scope `read` may
call it; a key that never opened a v2 position gets an empty page.
Responses carry `Cache-Control: private, no-store`.

## Query parameters

- `limit` integer
- `beforeId` integer
- `status` 'open'

## Response `200`

OK

- PmPaperV2PositionsResponse
  - `executionModel` 'pm_paper_v2', required
  - `positions` PmPaperV2Position[], required
    - `id` integer, required
    - `apiKeyId` integer, required
    - `source` 'polymarket' | 'kalshi', required
    - `slug` string, required
    - `title` string, required
    - `outcomeExternalMarketId` string, required
    - `side` 'yes' | 'no', required
    - `status` 'open' | 'closed_sold' | 'settled_win' | 'settled_loss', required
    - `openedAt` string, date-time, required
    - `settledAt` string, date-time, nullable, required: Set only when accountingStatus is `settled`.
    - `accountingStatus` 'open' | 'pending' | 'settled', required: pending = status is no longer open but the terminal record is not yet complete.
    - `quantityUnits2` string, required: Shares x 100.
    - `reservedCashQuanta6` string, required: Cash debited at entry, mUSD x 1,000,000.
    - `payoutQuanta6` string, nullable, required: mUSD x 1,000,000; null until settled.
    - `pnlQuanta6` string, nullable, required: Signed, mUSD x 1,000,000; null until settled.
    - `entry` object, required
      - `nativeIdentity` union, required
        - object
          - `venue` 'polymarket', required
          - `market` string, required: Condition id.
          - `tokenId` string, required: The exact token bought.
        - object
          - `venue` 'kalshi', required
          - `requestedTicker` string, required
          - `side` 'yes' | 'no', required: Native Kalshi side bought.
      - `quantity` string, required: Shares bought (decimal string).
      - `notional` string, required: Pre-fee cost, mUSD (decimal string).
      - `netFee` string, required: Fee, mUSD (decimal string).
      - `cashDebit` string, required: Total cash debited, mUSD (decimal string).
      - `bookReceivedAt` string, date-time, nullable, required: When the entry book was received.
      - `bookProviderAt` string, date-time, nullable, required: Venue timestamp of the entry book, when published.
      - `feeBasis` string, nullable, required: Fee policy or fee document revision used.
    - `exit` object, nullable, required: Latest exit intent; null when no close was requested.
      - `id` string, uuid, required
      - `status` 'pending' | 'leased' | 'retry' | 'manual_attention' | 'filled' | 'cancelled', required: pending/retry = waiting for the worker; leased = being executed; manual_attention = held for operator review; filled = closed; cancelled = withdrawn.
      - `accepted` boolean, required
      - `executed` boolean, required
      - `requestedAt` string, date-time, required
      - `nextAttemptAt` string, date-time, required
      - `lastError` string, nullable, required: Last worker failure code (e.g. a venue acquisition code).
      - `attentionHeld` boolean, required
    - `terminal` object, nullable, required: Close or settlement evidence; null until accountingStatus is `settled`.
      - `type` 'sell' | 'resolve', required
      - `evidenceBasis` 'acquired_book_full_sell' | 'provider_reported_final_binary_payout', required
      - `payoutQuanta6` string, required
      - `pnlQuanta6` string, required
      - `fee` string, nullable, required: Sell fee in mUSD; "0" for a resolution.
      - `acquiredAt` string, date-time, nullable, required
  - `hasMore` boolean, required
  - `nextBeforeId` integer, nullable, required
  - `risk` PmPaperV2Risk, required: Unpaginated exact totals for the calling key's v2 positions; "today" is the UTC day.
    - `asOf` string, date-time, required
    - `dayKey` string, date, required
    - `totalOpen` integer, required
    - `openReservedCashQuanta6` string, required
    - `openedToday` integer, required
    - `closedToday` integer, required
    - `realizedPnlTodayQuanta6` string, required: Signed, settled positions only.
    - `accountingComplete` boolean, required: False when any non-open position lacks a complete terminal record.
    - `legacyExposurePresent` boolean, required: True when the key also holds v1 PM positions, frozen cash, or non-cash assets.
  - `configuredHouse` object, nullable, required: This key's house enrollment; null when the key is not an enrolled house agent.
    - `userId` integer, required
    - `apiKeyId` integer, required
    - `walletId` integer, required
    - `houseAgentId` integer, required
    - `maxEndDays` integer
  - `entryEnabled` boolean, required: True when this key is enrolled and v2 entry is switched on.

## Other responses

- `400`: Unknown query parameter or invalid page (`invalid_page`).
- `401`: Missing/malformed or invalid/revoked API key
- `403`: API key missing the required scope
- `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": "..."}`.)
- `503`: Position read failed (`pm_positions_unavailable`).

---

[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)