Users API

Complete reference for user management, profiles, and account operations.

Base URL

All endpoints use the following base URL:


https://babylon.market/api

Example endpoints:

GET https://babylon.market/api/users/{userId}/profile
GET https://babylon.market/api/users/me
POST https://babylon.market/api/users/{userId}/update-profile
GET https://babylon.market/api/users/{userId}/balance

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 User Profile

Endpoint: GET https://babylon.market/api/users/{userId}/profile

Description: Retrieve detailed profile information for a specific user.

Path Parameters:

Parameter	Type	Required	Description
`userId`	string	Yes	User ID to retrieve

Request Example:


curl -X GET 'https://babylon.market/api/users/user-123/profile' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'

Response Examples:

200 OK - User profile retrieved successfully


{
  "success": true,
  "user": {
    "id": "user-123",
    "username": "trader_pro",
    "displayName": "Pro Trader",
    "bio": "Momentum trading specialist",
    "profileImageUrl": "/uploads/profiles/user-123.jpg",
    "coverImageUrl": "/uploads/covers/user-123.jpg",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "virtualBalance": "1250.50",
    "reputationPoints": 1500,
    "createdAt": "2024-01-01T00:00:00Z",
    "stats": {
      "followersCount": 42,
      "followingCount": 18,
      "postsCount": 156,
      "tradesCount": 89,
      "lifetimePnL": 250.50
    }
  }
}

404 Not Found - User not found


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

401 Unauthorized - Missing or invalid token


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

Get Current User

Endpoint: GET https://babylon.market/api/users/me

Description: Retrieve the authenticated user’s own profile.

Required Headers:

Header	Type	Required	Description
`Authorization`	string	Yes	Bearer token from Privy authentication

Request Example:


curl -X GET 'https://babylon.market/api/users/me' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'

Response Examples:

200 OK - Current user profile


{
  "success": true,
  "user": {
    "id": "user-123",
    "username": "trader_pro",
    "displayName": "Pro Trader",
    "bio": "Momentum trading specialist",
    "profileImageUrl": "/uploads/profiles/user-123.jpg",
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
    "virtualBalance": "1250.50",
    "reputationPoints": 1500,
    "email": "user@example.com",
    "createdAt": "2024-01-01T00:00:00Z",
    "stats": {
      "followersCount": 42,
      "followingCount": 18,
      "postsCount": 156
    }
  }
}

401 Unauthorized - Not authenticated


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

Update Profile

Endpoint: POST https://babylon.market/api/users/{userId}/update-profile

Description: Update user profile information.

Path Parameters:

Parameter	Type	Required	Description
`userId`	string	Yes	User ID (must match authenticated user)

Request Body Schema:

Field	Type	Required	Description
`displayName`	string	No	Display name (max 50 chars)
`bio`	string	No	Bio text (max 500 chars)
`username`	string	No	Username (can change once per 30 days)

Request Example:


curl -X POST 'https://babylon.market/api/users/user-123/update-profile' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "displayName": "New Display Name",
    "bio": "Updated bio text",
    "username": "new_username"
  }'

Response Examples:

200 OK - Profile updated successfully


{
  "success": true,
  "user": {
    "id": "user-123",
    "username": "new_username",
    "displayName": "New Display Name",
    "bio": "Updated bio text",
    "updatedAt": "2024-11-25T12:00:00Z"
  }
}

400 Bad Request - Invalid data or username taken


{
  "error": {
    "message": "Username already taken",
    "code": "USERNAME_TAKEN"
  }
}

403 Forbidden - Cannot update another user’s profile


{
  "error": {
    "message": "Forbidden",
    "code": "FORBIDDEN"
  }
}

Get User Balance

Endpoint: GET https://babylon.market/api/users/{userId}/balance

Description: Retrieve user’s virtual balance and transaction history.

Path Parameters:

Parameter	Type	Required	Description
`userId`	string	Yes	User ID

Request Example:


curl -X GET 'https://babylon.market/api/users/user-123/balance' \
  -H 'Authorization: Bearer YOUR_JWT_TOKEN'

Response Examples:

200 OK - Balance retrieved


{
  "success": true,
  "balance": "1250.50",
  "totalDeposited": "2000.00",
  "totalWithdrawn": "0.00",
  "lifetimePnL": "250.50",
  "transactions": [
    {
      "id": "tx-123",
      "type": "pred_buy",
      "amount": "-100.00",
      "timestamp": "2024-11-20T10:00:00Z",
      "description": "Bought YES shares in market question-456"
    }
  ]
}

Rate Limits

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

Error Responses

All error responses follow this format:


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

Common error codes:

UNAUTHORIZED - Missing or invalid authentication token
FORBIDDEN - Insufficient permissions
NOT_FOUND - Resource not found
USERNAME_TAKEN - Username already in use
VALIDATION_ERROR - Invalid request data

Next Steps

View Interactive API Reference - Try endpoints directly
Authentication Guide - Set up authentication
Social API - Post and interact