Markets API

Complete reference for prediction markets and perpetual futures APIs.

Base URL

All endpoints use the following base URL:


https://babylon.market/api

Example endpoints:

GET https://babylon.market/api/markets/predictions
POST https://babylon.market/api/markets/predictions/{id}/buy
POST https://babylon.market/api/markets/predictions/{id}/sell

Authentication

All endpoints require authentication using a JWT token obtained through Privy.

Required Header:


Authorization: Bearer <your-jwt-token>

See the Authentication guide for complete setup instructions.

Endpoints

Get Active Prediction Markets

Endpoint: GET https://babylon.market/api/markets/predictions

Description: Retrieve a list of active prediction markets with optional filtering.

Query Parameters:

Parameter	Type	Required	Description
`status`	string	No	Filter by status (`active`, `resolved`)
`userId`	string	No	Include user positions for this user
`page`	number	No	Page number (default: 1)
`limit`	number	No	Results per page (default: 20)

Request Example:


curl -X GET 'https://babylon.market/api/markets/predictions?status=active' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json'

Response Examples:

200 OK - Successful response


{
  "success": true,
  "questions": [
    {
      "id": "question-123",
      "questionNumber": 42,
      "text": "Will Bitcoin reach $100k by end of 2024?",
      "status": "active",
      "yesShares": 1250.5,
      "noShares": 1850.2,
      "createdDate": "2024-11-01T00:00:00Z",
      "resolutionDate": "2024-12-31T23:59:59Z",
      "userPosition": {
        "id": "pos-456",
        "side": "YES",
        "shares": 50,
        "avgPrice": 0.62,
        "currentPrice": 0.65,
        "unrealizedPnL": 7.5
      }
    }
  ],
  "count": 15
}

401 Unauthorized - Missing or invalid token


{
  "error": {
    "message": "Unauthorized",
    "code": "UNAUTHORIZED"
  }
}

400 Bad Request - Invalid query parameters


{
  "error": {
    "message": "Invalid status parameter",
    "code": "INVALID_PARAMETER"
  }
}

Buy Prediction Market Shares

Endpoint: POST https://babylon.market/api/markets/predictions/{id}/buy

Description: Purchase shares in a prediction market.

Path Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	Prediction market ID

Request Body:


{
  "outcome": "YES",
  "amount": 100
}

Request Body Schema:

Field	Type	Required	Description
`outcome`	string	Yes	Side to buy (`YES` or `NO`)
`amount`	number	Yes	Amount to spend (in virtual currency)

Request Example:


curl -X POST 'https://babylon.market/api/markets/predictions/question-123/buy' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "outcome": "YES",
    "amount": 100
  }'

Response Examples:

200 OK - Purchase successful


{
  "success": true,
  "position": {
    "id": "pos-789",
    "side": "YES",
    "shares": 38.46,
    "avgPrice": 0.65,
    "costBasis": 100
  },
  "newBalance": 900,
  "fees": {
    "total": 2,
    "platform": 1,
    "referrer": 1
  }
}

400 Bad Request - Insufficient balance or invalid request


{
  "error": {
    "message": "Insufficient balance",
    "code": "INSUFFICIENT_BALANCE"
  }
}

404 Not Found - Market not found


{
  "error": {
    "message": "Market not found",
    "code": "NOT_FOUND"
  }
}

Sell Prediction Market Shares

Endpoint: POST https://babylon.market/api/markets/predictions/{id}/sell

Description: Sell shares in a prediction market.

Path Parameters:

Parameter	Type	Required	Description
`id`	string	Yes	Prediction market ID

Request Body:


{
  "positionId": "pos-789",
  "shares": 20
}

Request Body Schema:

Field	Type	Required	Description
`positionId`	string	Yes	Position ID to sell from
`shares`	number	Yes	Number of shares to sell

Request Example:


curl -X POST 'https://babylon.market/api/markets/predictions/question-123/sell' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "positionId": "pos-789",
    "shares": 20
  }'

Response Examples:

200 OK - Sale successful


{
  "success": true,
  "proceeds": 52.50,
  "realizedPnL": 2.50,
  "remainingShares": 18.46,
  "newBalance": 952.50
}

400 Bad Request - Invalid position or insufficient shares


{
  "error": {
    "message": "Insufficient shares",
    "code": "INSUFFICIENT_SHARES"
  }
}

Rate Limits

Authenticated requests: 1000 requests per minute
Public endpoints: 100 requests per minute

Rate limit headers are included in all responses:

X-RateLimit-Limit - Maximum requests allowed
X-RateLimit-Remaining - Remaining requests in current window
X-RateLimit-Reset - Unix timestamp when limit resets

Error Responses

All error responses follow this format:


{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

Common error codes:

UNAUTHORIZED - Missing or invalid authentication token
INSUFFICIENT_BALANCE - Not enough virtual currency
INSUFFICIENT_SHARES - Not enough shares to sell
NOT_FOUND - Resource not found
INVALID_PARAMETER - Invalid request parameter
RATE_LIMIT_EXCEEDED - Too many requests

Next Steps

View Interactive API Reference - Try endpoints directly
Authentication Guide - Set up authentication
Trading Guide - Learn trading strategies