> ## Documentation Index
> Fetch the complete documentation index at: https://pmxt-sync-hosted-docs.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Fetch Positions
> List the open positions held by `address` across Polymarket, Opinion, and Limitless. Each position carries the market, outcome, share count, and average entry price.
Mark-to-market fields (`current_price`, `current_value`, `unrealized_pnl`) are reserved for a future release and currently return `null`.
**Available on:** Polymarket, Opinion, Limitless. Other venues raise `NotSupported` in hosted mode — for those, run a [local PMXT service](/guides/self-hosted).
Use any EVM private key. Your USDC sits in a non-custodial PreFundedEscrow on Polygon — for Polymarket, Opinion, and Limitless. PMXT cannot move funds without your EIP-712 signature.
## OpenAPI
````yaml /api-reference/openapi-hosted-trading.json get /v0/user/{address}/positions
openapi: 3.0.0
info:
title: PMXT Hosted Router API
description: Hosted-only endpoints for cross-venue search, matching, arbitrage, and SQL.
version: 49fbcd4
servers:
- url: https://trade.pmxt.dev
description: Hosted trading (v0)
security:
- bearerAuth: []
tags:
- name: Trading (Hosted)
description: >-
Hosted trading endpoints. Build / submit / cancel orders via
`trade.pmxt.dev/v0/*`. Hosted-mode is the default when `pmxt_api_key` is
set.
- name: Orders & Positions (Hosted)
description: >-
Hosted account reads. Open orders, fills, balances, and positions via
`trade.pmxt.dev/v0/*`. Requires `pmxt_api_key` + `wallet_address`.
- name: MatchedMarkets
description: Cross-venue matched market and event clusters.
- name: SQL
description: Direct read-only SQL access to the catalog (Enterprise).
paths:
/v0/user/{address}/positions:
get:
tags:
- Orders & Positions
summary: Fetch Positions
description: >-
List the open positions held by `address` across Polymarket, Opinion,
and Limitless. Each position carries the market, outcome, share count,
and average entry price.
Mark-to-market fields (`current_price`, `current_value`,
`unrealized_pnl`) are reserved for a future release and currently return
`null`.
operationId: fetchPositionsHosted
parameters:
- in: path
name: address
required: true
schema:
type: string
description: EVM wallet address.
responses:
'200':
description: Positions list.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/PositionV0'
'401':
description: Invalid or missing PMXT API key.
content:
application/json:
schema:
$ref: '#/components/schemas/HostedErrorResponse'
'503':
description: Catalog or indexer temporarily unavailable.
content:
application/json:
schema:
$ref: '#/components/schemas/HostedErrorResponse'
x-codeSamples:
- lang: python
label: Polymarket
source: >
# Hosted reads need: pmxt_api_key + wallet_address (private_key is
only required for writes).
import pmxt
client = pmxt.Polymarket(
pmxt_api_key="YOUR_PMXT_API_KEY",
wallet_address="0xYourWallet",
)
for position in client.fetch_positions():
print(position.market_id, position.shares, position.current_value)
- lang: javascript
label: Polymarket
source: >
// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only
required for writes).
import { Polymarket } from "pmxtjs";
const client = new Polymarket({
pmxtApiKey: "YOUR_PMXT_API_KEY",
walletAddress: "0xYourWallet",
});
for (const position of await client.fetchPositions()) {
console.log(position.marketId, position.shares, position.currentValue);
}
- lang: python
label: Opinion
source: >
# Hosted reads need: pmxt_api_key + wallet_address (private_key is
only required for writes).
import pmxt
client = pmxt.Opinion(
pmxt_api_key="YOUR_PMXT_API_KEY",
wallet_address="0xYourWallet",
)
for position in client.fetch_positions():
print(position.market_id, position.shares, position.current_value)
- lang: javascript
label: Opinion
source: >
// Hosted reads need: pmxtApiKey + walletAddress (privateKey is only
required for writes).
import { Opinion } from "pmxtjs";
const client = new Opinion({
pmxtApiKey: "YOUR_PMXT_API_KEY",
walletAddress: "0xYourWallet",
});
for (const position of await client.fetchPositions()) {
console.log(position.marketId, position.shares, position.currentValue);
}
components:
schemas:
PositionV0:
type: object
description: >-
Hosted-mode `Position` shape. `current_price`, `current_value`,
`entry_price`, `realized_pnl`, and `outcome_label` may be null when the
server doesn't yet have the data.
required:
- venue
- shares
properties:
venue:
type: string
enum:
- polymarket
- opinion
- limitless
description: >-
Venue the position is held on. Defaults to `polymarket` for tokens
whose source venue could not be inferred.
shares:
type: number
description: >-
Outcome shares held -- the ERC-1155, Opinion-native, or Limitless
token balance held by the PMXT PreFundedEscrow on behalf of the
wallet.
current_price:
type: number
nullable: true
description: >-
Current mark price in probability units [0, 1]. Always `null` in
this release -- server-side orderbook mark-to-market is not yet
batched (even with `with_mtm=true`).
current_value:
type: number
nullable: true
description: >-
Current mark-to-market value in USDC dollars (`shares *
current_price`). Always `null` in this release for the same reason
as `current_price`.
outcome_label:
type: string
nullable: true
description: >-
Human-readable outcome name (e.g. `Yes`), enriched from the user's
recorded buy fills. `null` when the user has no fill history for
this token in the operator DB.
entry_price:
type: number
nullable: true
description: >-
Cost-basis approximation: sum(buy USDC) / sum(buy shares) across all
of the user's buy fills for this token, in USDC-per-share. Ignores
sells -- lot-level matching is not yet implemented. `null` when
there are no recorded buy fills.
realized_pnl:
type: number
nullable: true
description: >-
Always `null` in this release. Derivation requires lot-level
matching of sell fills, which is not yet implemented.
HostedErrorResponse:
type: object
description: >-
Error envelope returned by `trade.pmxt.dev/v0/*` endpoints. Mirrors the
`ErrorDetail` shape used inside `BaseResponse.error` from the sidecar
spec.
required:
- error
properties:
error:
type: object
description: Structured error envelope. Always present on non-2xx responses.
properties:
message:
type: string
description: Human-readable explanation safe to surface to end users.
code:
type: string
description: >-
Stable hosted-mode error code. Use this (not `message`) for
branching in client code.
enum:
- HOSTED_TRADING_ERROR
- INSUFFICIENT_ESCROW_BALANCE
- ORDER_SIZE_TOO_SMALL
- INVALID_API_KEY
- OUTCOME_NOT_FOUND
- CATALOG_UNAVAILABLE
- BUILT_ORDER_EXPIRED
- INVALID_SIGNATURE
- NO_LIQUIDITY
- MISSING_WALLET_ADDRESS
- ORDER_NOT_FOUND
- INVALID_ORDER
retryable:
type: boolean
description: >-
`true` when the same request may succeed if retried (e.g.
transient catalog outage); `false` when the caller must change
inputs first.
exchange:
type: string
nullable: true
description: >-
Source venue that produced the error (e.g. `polymarket`,
`opinion`, `limitless`), when the failure originated upstream of
PMXT. `null` for PMXT-side errors.
detail:
type: object
additionalProperties: {}
nullable: true
description: >-
Free-form structured diagnostics (e.g. required minimum size,
escrow balance available). Shape varies per `code`.
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: >-
Required when calling the hosted API directly (curl, requests, fetch).
SDK users pass credentials via constructor params instead.
````