Skip to main content

​
Base URL

EnvironmentBase URL
Staginghttps://api-staging.promethex.market
Productionhttps://api.promethex.market
All endpoints use the /api/v1/ prefix. 
https://api-staging.promethex.market/api/v1/{endpoint}

​
Authentication

PrometheX uses Privy JWT tokens. Include the token in the Authorization header for authenticated endpoints: 
Authorization: Bearer eyJhbGciOiJFUzI1NiIs...
Read-only endpoints (market listings, details, prices) are public. Any state-changing operation (trading, profile updates) requires authentication. See the Authentication page for the full flow.

​
Response Format

Every response follows this envelope: 
{
  "code": 0,
  "reason": "",
  "msg": "success",
  "data": { ... }
}
​
code
number
0 for success, non-zero for errors. See Error Codes.
​
reason
string
Machine-readable error key (e.g., PARAM, NOT_FOUND). Empty on success.
​
msg
string
Human-readable message.
​
data
object
Response payload. Varies by endpoint. null on error.

​
Success Example

{
  "code": 0,
  "reason": "",
  "msg": "success",
  "data": {
    "totalCount": 42,
    "markets": [...]
  }
}

​
Error Example

{
  "code": 110101,
  "reason": "PARAM",
  "msg": "marketAddress is required",
  "data": null
}

​
Error Code Ranges

RangeCategoryDescription
110100–110199ClientBad request, missing params, not found
110200–110299ServerInternal errors, database, cache
110300–110399Third-partyExternal service failures
See the full Error Reference for all codes and remediation steps.

​
Pagination

List endpoints accept page (1-indexed) and pageSize query parameters: 
curl "https://api-staging.promethex.market/api/v1/market/get-markets?page=1&pageSize=20"
​
page
number
required
Page number, starting from 1.
​
pageSize
number
required
Items per page. Maximum 50.
Paginated responses include a totalCount field for calculating total pages.

​
Base Token Filter

Most market endpoints accept an optional baseTokenAddress query parameter to filter by the collateral token (e.g., USDC vs Points): 
GET /api/v1/market/get-markets?page=1&pageSize=10&baseTokenAddress=0x...

​
HTTP Methods

MethodUsage
GETRead operations — markets, users, positions, prices
POSTWrite operations — trading, profile updates, SSE connections

​
CORS

All origins are allowed. Supported methods: GET, POST, OPTIONS.

​
Rate Limiting

The API uses BBR-based adaptive rate limiting. If you receive error code 110103 (PLEASE_WAIT), back off and retry with exponential delay. See Rate Limits for details.

​
Endpoint Map

SectionEndpointsAuthDescription
Markets8+MixedList, search, and query market data
Trading4YesBuy, sell, claim, and view positions
Liquidity2YesAdd and remove liquidity
Resolution2YesSettle markets, check status
Real-time3YesSSE event streaming
Users5MostlyLogin, profile, notifications
Community4MixedPosts, comments

Quickstart

Get trading in 5 steps

Authentication

Privy JWT flow