---
title: "One entity in full"
method: GET
path: "/v1/entities/{id}"
tags: ["Board"]
---

# One entity in full

`GET /v1/entities/{id}`

## Request

- Base URL: `https://api.pmwallets.com`
- URL: `https://api.pmwallets.com/v1/entities/{id}`
- Auth: API key in header `x-api-key`

Figures, badges, PnL curve, wallets and recent fills. Subscribers (active push or plan) open any entity, spending 1 daily distinct-entity unit; others only the free sample or entities they paid to unlock. A raw address you do not hold: 403 not_unlocked with handle and price. Never charges.

## Path parameters

- `id` string, required

## Query parameters

- `period` string

## Response `200`

OK

- Entity
  - `periodId` string
  - `entityId` string: Handle, or the address if you hold it.
  - `label` string
  - `tier` 'free' | 'subscriber'
  - `revealed` boolean
  - `revealCents` integer: Unlock price now (0 = free band).
  - `viaPlan` boolean
  - `plan` PlanUsage: The caller's plan and what is left of its unlock allowance (present when signed in).
    - `state` 'active' | 'grace' | 'none'
    - `tier` string, nullable
    - `graceUntil` string, nullable
    - `daily` integer
    - `dailyUsed` integer
    - `monthly` integer
    - `monthlyUsed` integer
    - `pushSlots` integer
    - `pushActive` integer
  - `subscribed` boolean
  - `badges` string[]
  - `tagVersion` integer
  - `categories` object[]
    - `category` string
    - `share` number
  - `stats` LeaderboardRow
    - `entityId` string: Handle until you hold the address, then the 0x address. Pass it back to other endpoints as-is.
    - `label` string: Masked address (0x4b96…984e) until you hold it, then the full address.
    - `revealed` boolean: You hold the address (paid unlock, a still-free free unlock, or an active plan unlock).
    - `revealCents` integer: What unlocking this address costs now (0 = free band). Absent when not for sale (prices not published for the window).
    - `subscribed` boolean: You have an active push subscription to it.
    - `subscriptionId` string: Present when subscribed.
    - `viaPlan` boolean: Held only through your plan; masked again when the plan ends.
    - `unlockedBy` 'paid' | 'free' | 'plan' | 'null', nullable: mine=1 only: how you hold it; null = lapsed (masked again).
    - `pausedReason` string: mine=1 only: your subscription to it is paused for this reason.
    - `wallets` integer: Addresses of the entity that traded in the window.
    - `conditions` integer: Markets traded in the window.
    - `eligible` integer: Settled markets counted (wins + losses + breakevens).
    - `wins` integer
    - `losses` integer
    - `breakevens` integer
    - `excludedConditions` integer
    - `realizedPnl` number: Dollars.
    - `unrealizedPnl` number: Dollars.
    - `totalPnl` number: Dollars.
    - `grossBuyUsdc` number: Dollars spent buying in the window.
    - `feeUsdc` number
    - `roiOnBuys` number: realizedPnl / grossBuyUsdc (0.2 = 20%).
    - `nFills` integer
    - `pnlExTop` number: Realised PnL minus its single best settled market; decides the price band.
    - `pricePnlExTop` number, nullable
    - `wr` number, nullable
    - `lo` number, nullable
    - `hi` number, nullable
    - `status` 'active' | 'quiet' | 'dormant': Last fill <24h / <7d / older.
    - `statusAsOf` string, nullable
    - `style` 'maker' | 'taker' | 'two-sided' | 'null', nullable: By share of traded value made as maker (>=0.8 maker, <=0.2 taker).
    - `makerShare` number, nullable
    - `categories` object[]
      - `category` 'crypto-updown' | 'crypto' | 'esports' | 'sports' | 'politics' | 'economy' | 'geopolitics' | 'science-tech' | 'culture' | 'other' | 'unknown'
      - `share` number
    - `activity` Activity
      - `nFills` integer
      - `firstFillTs` string, nullable
      - `lastFillTs` string, nullable
      - `lastFillBlock` integer
      - `activeDays` integer
      - `fills24h` integer
      - `fills7d` integer
      - `windowEndTs` string, nullable
      - `makerFills` number, nullable
      - `makerUsdc` number, nullable
      - `usdc` number, nullable
    - `dataSource` 'live' | 'frozen'
    - `dataPeriodId` string
    - `dataAsOf` string, nullable
  - `history` object, nullable: Set when a notable share of markets were opened before the ledger begins.
    - `partialPct` number
    - `since` string
  - `dataSource` 'live' | 'frozen'
  - `dataPeriodId` string
  - `dataAsOf` string, nullable
  - `status` 'active' | 'quiet' | 'dormant'
  - `statusAsOf` string, nullable
  - `pnlCurve` object: PnL from genesis to the end of each day.
    - `locked` boolean
    - `since` string, nullable
    - `through` string, nullable
    - `fromGenesis` boolean
    - `points` object[]
      - `day` string
      - `pnl` number
  - `wallets` object[]
    - `wallet` string: Masked unless you subscribe to the entity.
    - `kind` string
    - `method` string
  - `fills` EntityFill[]
    - `block` integer
    - `logIndex` integer
    - `blockHash` string
    - `ts` string
    - `txHash` string
    - `wallet` string
    - `role` string
    - `side` string
    - `tokenId` string
    - `price` string
    - `shares` string: 1e-6 units.
    - `usdc` string: 1e-6 units.
    - `fee` string: 1e-6 units.
    - `exchange` string
    - `conditionId` string
    - `marketTitle` string
    - `marketSlug` string
    - `eventSlug` string
  - `tags` object
  - `fillSample` integer: Row cap applied to `fills` (100 subscribed, else 10).
  - `fillsDelayedMs` integer: 0 when subscribed, else 900000 (15 min).
  - `views` object: Subscriber tier: the distinct-entity budget after this call.
    - `usedToday` integer
    - `cap` integer

## Other responses

- `400`: Not a handle or 0x address, unknown handle, or unknown period.
- `401`: No valid API key (missing, malformed, unknown or revoked).
- `403`: `error: not_unlocked` (address you do not hold; body has entityId = handle, label, revealCents), the daily distinct-entity limit, or outside the free sample (needs a subscription or a paid unlock).
- `404`: No published stats for this entity in the window.
- `429`: Rate limited. Per IP 240/min overall and 180/min on the board and entity routes; per account 120/min (anonymous 60/min per IP) on board, entity and market reads. A `retry-after` header may be set.
- `503`: Temporarily unavailable; nothing was charged. Retry shortly.

---

[API](https://skmtc.dev/pmwallets/apis/pmwallets-api.md) · [All operations](https://skmtc.dev/pmwallets/apis/pmwallets-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pmwallets/apis/pmwallets-api/revisions/d5023fb40430?raw)