---
title: "Mock prediction-market positions + unrealized mark"
method: GET
path: "/api/agent/positions/pm"
tags: ["reads"]
---

# Mock prediction-market positions + unrealized mark

`GET /api/agent/positions/pm`

## Request

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

Up to 200 positions (open and historical). Supports `updatedSince`
delta polling — open/settlement/void all bump a position's row (use
the response's `asOf` as the next cursor). Requires scope `read`.

## Query parameters

- `updatedSince` string, date-time

## Response `200`

OK

- object
  - `positions` PmPosition[]
    - `id` integer
    - `status` string
    - `source` string
    - `eventSlug` string
    - `eventTitle` string
    - `outcome` object
      - `externalMarketId` string
      - `label` string
      - `tokenId` string, nullable
    - `side` 'yes' | 'no': Which side of the binary outcome the position backs.
    - `fillBasis` string
    - `entryProbability` number
    - `entryProbSum` number
    - `stakeMusd` number
    - `sharesMusd` number
    - `maxPayout` number: equals sharesMusd
    - `shape` string
    - `marketsCount` integer, nullable: True total markets on the event (stored value); may exceed the number of hydrated/snapshot outcomes for capped multi-outcome books. null when unknown.
    - `entryOutcomesSnapshot` union: Snapshot of the event's outcomes (names + probabilities) frozen at entry — the basis the position was priced against.
      - object
      - unknown[]
        - unknown
    - `freshnessAtEntry` Freshness: Data-freshness descriptor. Futures + spot use ageSeconds; PM uses ageMinutes. `status` is a freshness label; `basis` (PM only) names which timestamp the age was measured against.
      - `asOf` string, date-time, nullable
      - `ageSeconds` number, nullable: futures / spot
      - `ageMinutes` number, nullable: PM
      - `status` 'fresh' | 'lagging' | 'stale' | 'unknown' | 'null', nullable: fresh | lagging (PM only) | stale | unknown. PM lagging>=45m & stale>=2h; spot/futures stale>120s.
      - `basis` 'latest_snapshot' | 'source_update' | 'processed' | 'event_update' | 'unknown', nullable: PM only — which timestamp the age was measured against.
    - `eventStatusAtEntry` string, nullable: The event's status (e.g. open/closed) when the position opened.
    - `settlementState` string, nullable
    - `voidReason` string, nullable: Why a position was voided and refunded (status void_refunded) — null for normal settlements.
    - `payoutMusd` number, nullable
    - `pnlMusd` number, nullable
    - `openedAt` string, date-time, nullable
    - `settledAt` string, date-time, nullable
    - `createdAt` string, date-time
    - `currentProbability` number, nullable: list endpoint, open only; 0..100
    - `unrealizedMark` number, nullable
    - `unrealizedPnl` number, nullable
    - `relatedCoins` string[]: List endpoint, open positions only: slugs of the coins the event is DIRECTLY about (admin-rejected links excluded), sorted; empty = no linked coin. Omitted when it could not be read (treat as unknown).
    - `eventEndDate` string, date-time, nullable: List endpoint, open positions only: the venue's own event end date, passed through unchanged. Venues publish null or sentinel values, so treat implausible dates as unknown. Omitted when it could not be read.
  - `updatedSince` string, date-time, nullable
  - `asOf` string, date-time

## Other responses

- `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": "..."}`.)

---

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