API Reference

Complete documentation for all PMF API endpoints.

No Authentication Required

The API is currently FREE with no authentication needed. All examples below work without API keys!

Base URL

https://api.pmf.finance/api/v1

Portfolio Groups

List All Groups

Get a list of all available PMF groups.

GET /api/v1/groups/

Query Parameters:

• page (integer) - Page number (default: 1)
• page_size (integer) - Items per page (default: 50, max: 100)
• search_term (string) - Search in title and description

Example Request:

curl "https://api.pmf.finance/api/v1/groups/?page=1&page_size=20"

Response:

{
  "groups": [
    {
      "id": "7d51fd93-d7d5-4574-8f49-f9ec0d2cda35",
      "title": "US Government Shutdown 2026",
      "description": "Hedge your financial risk to a government shutdown",
      "group_type": "portfolio",
      "is_paper_trading": true,
      "initial_capital": 100.0,
      "current_cash": 39.58,
      "markets_count": 5,
      "created_at": "2026-01-27T17:20:27.282459Z",
      "updated_at": "2026-02-04T01:00:14.813595Z"
    }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20
}

Get Group Details

Get detailed information about a specific group.

GET /api/v1/groups/{group_id}

Parameters:

• group_id (uuid) - The group identifier

Example Request:

curl "https://api.pmf.finance/api/v1/groups/7d51fd93-d7d5-4574-8f49-f9ec0d2cda35"

Response:

{
  "id": "7d51fd93-d7d5-4574-8f49-f9ec0d2cda35",
  "title": "US Government Shutdown 2026",
  "description": "Hedge your financial risk...",
  "group_type": "portfolio",
  "markets": [
    {
      "market_id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Government shutdown lasts >10 days",
      "platform": "polymarket",
      "weight": 0.4,
      "current_price": 0.35,
      "added_at": "2026-01-30T10:00:00Z"
    }
  ],
  "metadata": {
    "pmf_version": "1.0",
    "term_length": "year",
    "rebalance_frequency": "weekly"
  },
  "created_at": "2026-01-27T17:20:27.282459Z"
}

Get NAV History (with Cache)

Retrieve historical NAV data with fast cached responses for daily data.

GET /api/v1/groups/{group_id}/nav-history

Query Parameters (Choose one approach):

Option 1: Interval-Based (Recommended)

• interval (string) - Time period: 1d, 7d, 30d, max (default: 1d)
• fidelity (integer) - Resolution in minutes: 60, 1440 (default: 1440 for daily)

Option 2: Timestamp-Based

• start_time (integer) - Start Unix timestamp
• end_time (integer) - End Unix timestamp
• fidelity (integer) - Resolution in minutes

Performance Tip

Use fidelity=1440 (daily) for the fastest response times. Daily data is pre-computed and cached!

Example Requests:

# Fast (cached) - Last 7 days with daily data
curl "https://api.pmf.finance/api/v1/groups/{group_id}/nav-history?interval=7d&fidelity=1440"

# Slower (real-time) - Last 24 hours with hourly data
curl "https://api.pmf.finance/api/v1/groups/{group_id}/nav-history?interval=1d&fidelity=60"

Response:

{
  "history": [
    {"t": 1769628938, "p": 99.02, "nav": 99.02, "cash_ratio": 0.0},
    {"t": 1769715338, "p": 91.57, "nav": 91.57, "cash_ratio": 0.0},
    {"t": 1769801738, "p": 85.23, "nav": 85.23, "cash_ratio": 0.0}
  ],
  "metadata": {
    "group_id": "7d51fd93-d7d5-4574-8f49-f9ec0d2cda35",
    "group_title": "US Government Shutdown 2026",
    "data_source": "cache",  // "cache" = fast, "real_time" = slower
    "cache_hit_rate": 1.0,   // 1.0 = 100% from cache
    "data_points": 7,
    "response_time_ms": 42    // Fast response indicates cache hit
  }
}

Get Latest NAV

Get the current NAV for a group.

GET /api/v1/groups/{group_id}/nav-latest

Example Request:

curl "https://api.pmf.finance/api/v1/groups/{group_id}/nav-latest"

Response:

{
  "group_id": "7d51fd93-d7d5-4574-8f49-f9ec0d2cda35",
  "nav": 39.58,
  "cash_ratio": 1.0,
  "timestamp": "2026-02-04T19:00:00Z"
}

Error Responses

All endpoints use standard HTTP status codes:

Code	Description
200	Success
201	Created
400	Bad Request - Invalid parameters
404	Not Found - Resource doesn't exist
422	Unprocessable Entity - Validation error
429	Too Many Requests - Rate limit exceeded
500	Internal Server Error

Error Response Format

{
  "detail": "Descriptive error message",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 45
}

Rate Limiting

All requests are subject to free tier limits (no authentication required):

• 60 requests per minute
• 1,000 requests per day
• 20,000 requests per month

Check response headers for current usage:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1707064800