API Reference

Authentication

GrokMarkets operates through Twitter commands with @PANAGOT. The API endpoints are primarily for data retrieval and internal Twitter bot operations. No wallet authentication is required for public data endpoints.

Markets API

GET /api/markets

Get All Markets

Retrieve all available prediction markets.

GET /api/markets

Response:
[
  {
    "id": "market_123",
    "question": "Will Bitcoin reach $100K by December 2025?",
    "creator": "crypto_trader",
    "totalYesAmount": 12.5,
    "totalNoAmount": 8.3,
    "resolved": false,
    "endTime": "2025-12-31T23:59:59Z",
    "createdAt": "2024-09-30T10:00:00Z"
  }
]
                    

POST /api/markets

Create Market (Twitter Integration)

Create a new prediction market via Twitter bot integration. This endpoint is used internally by @PANAGOT when processing Twitter commands.

Parameter	Type	Required	Description
question	string	Yes	The prediction question
endTime	string (ISO 8601)	Yes	Market end date and time
creatorFee	number	No	Creator fee in basis points (default: 300)

POST /api/markets
Content-Type: application/json

{
  "question": "Will Tesla reach $500 by end of 2024?",
  "endTime": "2024-12-31T23:59:59Z",
  "creatorFee": 300
}
                    

GET /api/markets/:id

Get Market Details

Retrieve detailed information about a specific market.

GET /api/markets/market_123

Response:
{
  "id": "market_123",
  "question": "Will Bitcoin reach $100K by December 2025?",
  "creator": "crypto_trader",
  "totalYesAmount": 12.5,
  "totalNoAmount": 8.3,
  "resolved": false,
  "outcome": null,
  "endTime": "2025-12-31T23:59:59Z",
  "createdAt": "2024-09-30T10:00:00Z",
  "bets": [...],
  "stats": {...}
}
                    

Bets API

POST /api/bets

Place Bet (Twitter Integration)

Place a bet on a prediction market via Twitter bot integration. This endpoint is used internally by @PANAGOT when processing betting replies.

Parameter	Type	Required	Description
marketId	string	Yes	The market ID to bet on
amount	number	Yes	Bet amount in SOL
isYes	boolean	Yes	True for YES bet, false for NO bet
twitterHandle	string	Yes	User's Twitter handle

POST /api/bets
Content-Type: application/json

{
  "marketId": "market_123",
  "amount": 1.5,
  "isYes": true,
  "twitterHandle": "crypto_trader"
}
                    

GET /api/markets/:id/bets

Get Market Bets

Retrieve all bets for a specific market.

GET /api/markets/market_123/bets

Response:
[
  {
    "id": "bet_456",
    "marketId": "market_123",
    "userTwitterHandle": "crypto_trader",
    "side": "YES",
    "amount": 1.5,
    "odds": 0.581,
    "potentialPayout": 2.58,
    "createdAt": "2024-09-30T10:30:00Z"
  }
]
                    

Users API

GET /api/users/:handle/balance

Get User Balance

Retrieve a user's current balance. Used internally by @PANAGOT when processing balance check commands.

GET /api/users/crypto_trader/balance

Response:
{
  "balance": 15.75,
  "currency": "SOL"
}
                    

GET /api/users/:handle/transactions

Get User Transactions

Retrieve a user's transaction history.

GET /api/users/crypto_trader/transactions

Response:
[
  {
    "id": "tx_789",
    "type": "bet",
    "amount": 1.5,
    "marketId": "market_123",
    "createdAt": "2024-09-30T10:30:00Z",
    "status": "confirmed"
  }
]
                    

System API

GET /api/health

Health Check

Check the API health status and database connectivity.

GET /api/health

Response:
{
  "status": "ok",
  "timestamp": "2025-01-10T10:00:00Z",
  "message": "GrokMarkets API is running",
  "database": {
    "connected": true,
    "status": "healthy"
  }
}
                    

GET /api/stats

Platform Statistics

Get overall platform statistics.

GET /api/stats

Response:
{
  "totalMarkets": 156,
  "totalBets": 2847,
  "totalVolume": 1250.75,
  "activeUsers": 892,
  "resolvedMarkets": 89
}
                    

Error Responses

All API endpoints return consistent error responses:

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

Common HTTP Status Codes:

200 - Success
400 - Bad Request
401 - Unauthorized
404 - Not Found
500 - Internal Server Error

Table of Contents