Get Positions

Retrieve your open positions across all platforms. Positions include unrealized P&L and current market values.

Endpoint

GET https://api.matchr.xyz/v1/positions

Query Parameters

platform

string

Filter by platform: polymarket, kalshi, or all

status

string

default:"open"

Position status: open, closed, all

wallet_id

string

Filter by specific wallet

Example Request

curl -X GET "https://api.matchr.xyz/v1/positions?status=open" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

success

boolean

Whether the request succeeded

data

array

Array of position objects

Show Position Object

string

Unique position identifier

market_id

string

Market identifier

event_id

string

Parent event identifier

platform

string

Platform (polymarket, kalshi)

event_title

string

Event title/question

outcome

string

Position outcome (Yes, No, etc.)

side

string

Position side: long or short

size

number

Position size (number of shares)

average_price

number

Average entry price

current_price

number

Current market price

cost_basis

number

Total cost in USD

market_value

number

Current market value in USD

unrealized_pnl

number

Unrealized profit/loss in USD

unrealized_pnl_pct

number

Unrealized profit/loss percentage

created_at

string

When the position was opened

Example Response

{
  "success": true,
  "data": [
    {
      "id": "pos_xyz789",
      "market_id": "mkt_yes123",
      "event_id": "evt_123abc",
      "platform": "polymarket",
      "event_title": "Will Trump win the 2024 election?",
      "outcome": "Yes",
      "side": "long",
      "size": 500,
      "average_price": 0.45,
      "current_price": 0.52,
      "cost_basis": 225.00,
      "market_value": 260.00,
      "unrealized_pnl": 35.00,
      "unrealized_pnl_pct": 15.56,
      "created_at": "2024-10-01T10:30:00Z"
    },
    {
      "id": "pos_xyz790",
      "market_id": "mkt_no456",
      "event_id": "evt_456def",
      "platform": "kalshi",
      "event_title": "Will Bitcoin hit $100K in 2024?",
      "outcome": "No",
      "side": "long",
      "size": 200,
      "average_price": 0.60,
      "current_price": 0.55,
      "cost_basis": 120.00,
      "market_value": 110.00,
      "unrealized_pnl": -10.00,
      "unrealized_pnl_pct": -8.33,
      "created_at": "2024-10-10T15:45:00Z"
    }
  ],
  "summary": {
    "total_positions": 2,
    "total_cost_basis": 345.00,
    "total_market_value": 370.00,
    "total_unrealized_pnl": 25.00,
    "total_unrealized_pnl_pct": 7.25
  }
}

Get Single Position

Retrieve details for a specific position.

Endpoint

GET https://api.matchr.xyz/v1/positions/{position_id}

Example Request

curl -X GET "https://api.matchr.xyz/v1/positions/pos_xyz789" \
  -H "Authorization: Bearer YOUR_API_KEY"

Position History

Get the trade history for a position.

Endpoint

GET https://api.matchr.xyz/v1/positions/{position_id}/history

Response

{
  "success": true,
  "data": {
    "position_id": "pos_xyz789",
    "trades": [
      {
        "id": "trd_001",
        "type": "buy",
        "size": 300,
        "price": 0.42,
        "cost": 126.00,
        "timestamp": "2024-10-01T10:30:00Z"
      },
      {
        "id": "trd_002",
        "type": "buy",
        "size": 200,
        "price": 0.495,
        "cost": 99.00,
        "timestamp": "2024-10-05T14:15:00Z"
      }
    ],
    "summary": {
      "total_buys": 500,
      "total_sells": 0,
      "average_buy_price": 0.45,
      "average_sell_price": null,
      "total_fees": 1.12
    }
  }
}

Portfolio Summary

Get a high-level summary of your entire portfolio.

Endpoint

GET https://api.matchr.xyz/v1/portfolio

Query Parameters

period

string

default:"1d"

Time period for performance: 1d, 7d, 30d, 90d, 1y, all

Example Request

curl -X GET "https://api.matchr.xyz/v1/portfolio?period=30d" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "total_value": 5420.50,
    "cash_balance": 1500.00,
    "positions_value": 3920.50,
    "unrealized_pnl": 320.50,
    "unrealized_pnl_pct": 8.91,
    "realized_pnl_period": 150.00,
    "performance": {
      "period": "30d",
      "start_value": 5000.00,
      "end_value": 5420.50,
      "return_usd": 420.50,
      "return_pct": 8.41
    },
    "allocation": {
      "polymarket": {
        "value": 2800.00,
        "percentage": 51.66
      },
      "kalshi": {
        "value": 1120.50,
        "percentage": 20.67
      },
      "cash": {
        "value": 1500.00,
        "percentage": 27.67
      }
    },
    "by_category": {
      "politics": { "value": 2100.00, "pnl": 200.00 },
      "sports": { "value": 1200.50, "pnl": 80.50 },
      "crypto": { "value": 620.00, "pnl": 40.00 }
    }
  }
}

Closed Positions

Get your closed/resolved positions and realized P&L.

Endpoint

GET https://api.matchr.xyz/v1/positions?status=closed

Example Response

{
  "success": true,
  "data": [
    {
      "id": "pos_closed001",
      "market_id": "mkt_resolved123",
      "event_id": "evt_resolved123",
      "platform": "polymarket",
      "event_title": "Will Fed cut rates in September 2024?",
      "outcome": "Yes",
      "resolution": "Yes",
      "won": true,
      "size": 1000,
      "average_price": 0.65,
      "exit_price": 1.00,
      "cost_basis": 650.00,
      "proceeds": 1000.00,
      "realized_pnl": 350.00,
      "realized_pnl_pct": 53.85,
      "closed_at": "2024-09-18T14:00:00Z"
    }
  ]
}

Redeem Resolved Positions

Redeem winnings from resolved markets.

Endpoint

POST https://api.matchr.xyz/v1/positions/{position_id}/redeem

Example Request

curl -X POST "https://api.matchr.xyz/v1/positions/pos_resolved123/redeem" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "success": true,
  "data": {
    "position_id": "pos_resolved123",
    "amount_redeemed": 1000.00,
    "transaction_hash": "0x123abc...",
    "redeemed_at": "2024-10-15T16:00:00Z"
  }
}

Error Codes

Code	Description
`400`	Invalid parameters
`401`	Missing or invalid API key
`404`	Position not found
`409`	Position not redeemable (not resolved)
`429`	Rate limit exceeded
`500`	Server error

API Reference

Market Data

Trading

Advanced

Get Positions

Get Positions

Endpoint

Query Parameters

Example Request

Response

Example Response

Get Single Position

Endpoint

Example Request

Position History

Endpoint

Response

Portfolio Summary

Endpoint

Query Parameters

Example Request

Response

Closed Positions

Endpoint

Example Response

Redeem Resolved Positions

Endpoint

Example Request

Response

Error Codes

API Reference

Market Data

Trading

Advanced

​Get Positions

​Endpoint

​Query Parameters

​Example Request

​Response

​Example Response

​Get Single Position

​Endpoint

​Example Request

​Position History

​Endpoint

​Response

​Portfolio Summary

​Endpoint

​Query Parameters

​Example Request

​Response

​Closed Positions

​Endpoint

​Example Response

​Redeem Resolved Positions

​Endpoint

​Example Request

​Response

​Error Codes

Get Positions

Endpoint

Query Parameters

Example Request

Response

Example Response

Get Single Position

Endpoint

Example Request

Position History

Endpoint

Response

Portfolio Summary

Endpoint

Query Parameters

Example Request

Response

Closed Positions

Endpoint

Example Response

Redeem Resolved Positions

Endpoint

Example Request

Response

Error Codes