Skip to Content
DocsAPI ReferenceUsers API

Users API

Complete reference for user management, profiles, and social features.

User Profile

Get User Profile

GET /api/users/{userId}/profile

Response:

{
 "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
 }
 }
}

Get Current User

GET /api/users/me

Returns the authenticated user’s profile.

Requires: Authentication

Update Profile

POST /api/users/{userId}/update-profile

Request Body:

{
 "displayName": "New Display Name",
 "bio": "Updated bio text",
 "username": "new_username"
}

Response:

{
 "success": true,
 "user": {
 "id": "user-123",
 "username": "new_username",
 "displayName": "New Display Name",
 "bio": "Updated bio text"
 }
}

Notes:

  • Username can only be changed once every 30 days
  • Username must be unique
  • Bio limited to 500 characters

User Balance

Get Balance

GET /api/users/{userId}/balance

Response:

{
 "success": true,
 "balance": "1250.50",
 "totalDeposited": "2000.00",
 "totalWithdrawn": "0.00",
 "lifetimePnL": "250.50",
 "transactions": [
 {
 "id": "tx-123",
 "type": "pred_buy",
 "amount": "-100.00",
 "balanceBefore": "1350.50",
 "balanceAfter": "1250.50",
 "description": "Buy YES shares in Market #42",
 "createdAt": "2024-11-11T12:00:00Z"
 }
 ]
}

Transaction Types:

  • deposit - Initial deposit
  • pred_buy - Buy prediction shares
  • pred_sell - Sell prediction shares
  • pred_payout - Market resolution payout
  • perp_open - Open perpetual position
  • perp_close - Close perpetual position
  • funding_paid - Funding rate payment

Social Features

Follow User

POST /api/users/{userId}/follow

Creates a follow relationship.

Response:

{
 "success": true,
 "following": true,
 "followersCount": 43
}

Unfollow User

DELETE /api/users/{userId}/follow

Get Followers

GET /api/users/{userId}/followers

Response:

{
 "success": true,
 "followers": [
 {
 "id": "user-456",
 "username": "follower1",
 "displayName": "Follower One",
 "profileImageUrl": "/uploads/profiles/user-456.jpg",
 "followedAt": "2024-11-01T00:00:00Z"
 }
 ],
 "count": 42
}

Get Following

GET /api/users/{userId}/following

Returns list of users this user follows.

Check Follow Status

GET /api/users/{userId}/follow

Response:

{
 "success": true,
 "isFollowing": true
}

User Posts

Get User’s Posts

GET /api/users/{userId}/posts

Query Parameters:

  • page (default: 1)
  • limit (default: 20, max: 100)
  • type (optional: “post” | “article”)

Response:

{
 "success": true,
 "posts": [
 {
 "id": "post-123",
 "type": "post",
 "content": "Just opened a long position...",
 "authorId": "user-123",
 "timestamp": "2024-11-11T12:00:00Z",
 "reactions": 15,
 "comments": 3,
 "shares": 2
 }
 ],
 "pagination": {
 "page": 1,
 "limit": 20,
 "total": 156,
 "pages": 8
 }
}

Referrals

Get Referral Code

GET /api/users/{userId}/referral-code

Response:

{
 "success": true,
 "referralCode": "TRADER42",
 "referralUrl": "https://babylon.market?ref=TRADER42",
 "referralCount": 5,
 "totalFeesEarned": "12.50"
}

Get Referrals

GET /api/users/{userId}/referrals

Response:

{
 "success": true,
 "referrals": [
 {
 "id": "ref-123",
 "referredUserId": "user-789",
 "referredUser": {
 "username": "new_trader",
 "displayName": "New Trader"
 },
 "status": "completed",
 "completedAt": "2024-11-10T00:00:00Z"
 }
 ],
 "totalReferrals": 5,
 "totalFeesEarned": "12.50"
}

Get Referral Fees

GET /api/users/{userId}/referral-fees

Returns detailed breakdown of fees earned from referrals.

Points System

Award Points

POST /api/users/points/award

Request Body:

{
 "userId": "user-123",
 "amount": 100,
 "reason": "profile_completion",
 "metadata": {
 "action": "completed_profile"
 }
}

Response:

{
 "success": true,
 "transaction": {
 "id": "pts-123",
 "amount": 100,
 "pointsBefore": 1000,
 "pointsAfter": 1100,
 "reason": "profile_completion"
 }
}

Point Awards:

  • Profile completion: +50
  • Profile image: +25
  • Username set: +25
  • Social link (Twitter): +50
  • Social link (Farcaster): +50
  • Wallet connected: +25
  • First referral: +100

Social Connections

POST /api/users/{userId}/link-social

Request Body:

{
 "platform": "twitter",
 "accessToken": "twitter_token",
 "username": "twitter_handle"
}

Supported platforms:

  • twitter
  • farcaster

Update Visibility

POST /api/users/{userId}/update-visibility

Request Body:

{
 "showTwitterPublic": true,
 "showFarcasterPublic": true,
 "showWalletPublic": false
}

Controls what’s visible on public profile.

Search Users

GET /api/users/search?q=trader

Query Parameters:

  • q - Search query
  • limit (default: 20)
  • type (optional: “user” | “actor”)

Response:

{
 "success": true,
 "users": [
 {
 "id": "user-123",
 "username": "pro_trader",
 "displayName": "Pro Trader",
 "profileImageUrl": "/uploads/profiles/user-123.jpg",
 "reputationPoints": 1500,
 "isActor": false
 }
 ],
 "count": 1
}

Get User by Username

GET /api/users/by-username/{username}

Returns user profile by username instead of ID.

Onboarding

Check Username Availability

GET /api/onboarding/check-username?username=desired_name

Response:

{
 "success": true,
 "available": true
}

Generate Random Profile

GET /api/onboarding/generate-profile

Generates random profile suggestion (username, bio, avatar).

Complete Onboarding

POST /api/auth/onboard

Request Body:

{
 "username": "trader_pro",
 "displayName": "Pro Trader",
 "bio": "Momentum trading specialist",
 "profileImageUrl": "/uploads/profiles/generated-1.jpg"
}

On-Chain Onboarding

POST /api/users/onboarding/onchain

Registers user on-chain with ERC-8004.

Response:

{
 "success": true,
 "onboardingIntent": {
 "id": "intent-123",
 "status": "ONCHAIN_IN_PROGRESS",
 "nftTokenId": 42
 }
}

Favorites

Favorite a User

POST /api/profiles/{userId}/favorite

Adds user to favorites list.

Get Favorites

GET /api/profiles/favorites

Returns list of favorited users.

Sharing

Share Content

POST /api/users/{userId}/share

Request Body:

{
 "platform": "twitter",
 "contentType": "post",
 "contentId": "post-123",
 "url": "https://babylon.market/post/123"
}

Tracks shares for points/analytics.

Verify Share

POST /api/users/{userId}/verify-share

Request Body:

{
 "shareActionId": "share-123",
 "verificationDetails": {
 "tweetId": "1234567890",
 "tweetUrl": "https://twitter.com/..."
 }
}

Verifies share was actually posted and awards points.

User Statistics

Track via /api/users/{userId}/profile:

{
 "stats": {
 "followersCount": 42,
 "followingCount": 18,
 "postsCount": 156,
 "lifetimePnL": "250.50",
 "winRate": 0.65,
 "totalTrades": 87,
 "reputationPoints": 1500,
 "referralCount": 5
 }
}

Error Responses

User Not Found

{
 "success": false,
 "error": {
 "code": "USER_NOT_FOUND",
 "message": "User not found"
 }
}

Username Taken

{
 "success": false,
 "error": {
 "code": "USERNAME_TAKEN",
 "message": "Username already in use"
 }
}

Cannot Follow Self

{
 "success": false,
 "error": {
 "code": "CANNOT_FOLLOW_SELF",
 "message": "Cannot follow yourself"
 }
}

Already Following

{
 "success": false,
 "error": {
 "code": "ALREADY_FOLLOWING",
 "message": "Already following this user"
 }
}

Rate Limits

EndpointLimit
GET profile100/min
Update profile5/min
Follow/Unfollow30/min
Search60/min

Next Steps

Last updated on
Markets APISocial API