API Reference

Two APIs

All API and CLI access goes through the API gateway — a single entry point for all clients.

Base URL: https://api.poltrack.tech

OpenAPI spec: GET /openapi.json

Public endpoints (no auth): /v2/validators, /v2/pol-economics, /v2/tokenomics, /v2/preview Personal endpoints (Bearer token): /v2/me, /v2/dashboard, /v2/portfolio, /v2/staking, etc.

Authentication

Personal endpoints require a Bearer token — either a session token (sk_...) or an API key (pk_...).

Authorization: Bearer sk_... or pk_...

Session tokens are created via Privy login and expire in 14 days. API keys are created in Settings and expire in 90 days. One key per account.

Rate limits for API keys: 10 requests/minute, 1,000 requests/day.

Public data endpoints (no auth)

These are served by the web application. No authentication required.

GET /api/pol-economics

Complete POL token economics — supply, fees, burns, distribution, staking yield, chain activity.

GET /api/validators

All active validators with delegation, commission, performance, and POLTRACK Score.

GET /api/validators/[id]

Detailed validator data — history, score breakdown, delegation trends.

GET /api/validators/scores

Latest POLTRACK Score for all validators.

Personal endpoints (auth required)

GET /v2/me

Current user profile and capabilities.

GET /v2/dashboard

All-in-one snapshot: portfolio, positions, events, rewards, insights, income, anniversary, alerts.

POST /v2/wallets

Add a wallet to track. Body: {"address": "0x...", "label": "Main"}

GET /v2/portfolio

Portfolio breakdown: total, staked, liquid, CEX, price.

GET /v2/staking

Staking positions per validator with commission and unclaimed rewards.

GET /v2/activity

Delegation and reward events. Query: ?filter=all|delegate|claim&limit=500

GET /v2/rewards

Total rewards claimed across all wallets.

GET /v2/insights

Personal insights: monthly income, concentration risk, staker rank, APY gap, commission savings, validator quality, income trend.

GET /v2/alerts

Alert history.

POST /v2/token/regenerate

Revoke current API key and create a new one.

Telegram

Payments

Payment endpoints are disabled during beta.