API Reference
Welcome to the BlockBet API Reference documentation. This guide provides detailed information about all available GraphQL APIs, their parameters, and responses.
Getting Started​
The BlockBet API is built using GraphQL, providing a flexible and powerful way to interact with our services. To get started:
- Authentication: Authentication is handled automatically via HTTP cookies
- Base URL: All API requests should be made to our GraphQL endpoint
- Schema: Our API follows a strongly-typed schema for better development experience
API Structure​
Our API is organized into several main services:
-
GraphQL Main (gql-main): Core API for user-facing operations
- Authentication: User registration, login, and MFA management
- User Management: Profile, settings, and wallet operations
- Betting: Place bets, view history, and manage betting operations
- Blockchain: Smart contract interactions and transaction management
-
GraphQL CRM (gql-crm): Admin-facing API for platform management
- Admin authentication and authorization
- User management and reporting
- System configuration and monitoring
-
Hooks: Event-based services for integrations and automated processes
- External system integrations
- Task management and scheduling
- Notification handling
-
WebSocket: Real-time communication for live updates
Authentication​
Authentication is handled automatically via HTTP cookies. The system manages both accessToken and refreshToken cookies, so there's no need to manually set the Authorization header.
When you successfully authenticate, the tokens will be set in cookies and automatically included in subsequent requests. The system handles token refreshing and session management without requiring manual header setup.
Rate Limiting​
To ensure fair usage, we implement rate limiting on our API endpoints:
- Short-term: 2 requests per second
- Medium-term: 7 requests per 10 seconds
- Long-term: 15 requests per minute
Error Handling​
Our API uses standard GraphQL error handling with detailed error messages and codes. Common error types include:
- Authentication errors
- Validation errors
- Rate limiting errors
- Business logic errors
Business Logic Errors​
| Category | Error Code | Description |
|---|---|---|
| User Account & Authentication | ||
| USER_NOT_FOUND | The requested user account does not exist | |
| USER_LOCKED/USER_BLOCKED/USER_DELETED | Account is unavailable due to security measures, violation of terms, or deletion | |
| USER_MFA_LOCKED | Account locked due to multiple failed multi-factor authentication attempts | |
| USER_KYC_LOCKED | Account locked pending Know Your Customer verification | |
| EMAIL_ALREADY_EXISTS/USERNAME_EXISTS | Registration failed due to duplicate credentials | |
| ALREADY_LINKED/ALREADY_LINKED_TO_OTHER_USER | Social account linking conflict | |
| Verification & Security | ||
| WRONG_CODE/WRONG_2FA_CODE | Incorrect verification or 2FA code provided | |
| INVALID_TOKEN/TOKEN_EXPIRED | Authentication token is invalid or has expired | |
| MFA_NOT_ENABLED/MFA_ALREADY_ENABLED | Multi-factor authentication status conflict | |
| KYC_REQUIRED | This operation requires completed identity verification | |
| EMAIL_NOT_VERIFIED/PHONE_ALREADY_VERIFIED | Account verification status conflict | |
| Financial Operations | ||
| INSUFFICIENT_BALANCE | Account lacks funds to complete the requested transaction | |
| LESS_THAN_MINIMUM_WITHDRAWAL_AMOUNT | Withdrawal amount below minimum threshold | |
| CLAIM_REWARDS_LOCKED/WITHDRAWAL_BLOCKS_LOCKED | Financial operations temporarily restricted | |
| NO_REWARDS_TO_CLAIM | No pending rewards available for claiming | |
| WAGERING_NOT_REACHED | Betting requirements not fulfilled for reward eligibility | |
| Events & Predictions | ||
| EVENT_NOT_FOUND/PREDICTION_NOT_FOUND | Requested event or prediction does not exist | |
| RESOLVED_EVENT/EVENT_ENDED | Operation not allowed on completed events | |
| PUBLISHED_EVENT | Cannot modify an event that has been made public | |
| PREDICTION_ALREADY_EXISTS | Duplicate prediction creation attempt | |
| EVENT_NOT_FOR_THIS_COUNTRY | Event restricted in user's geographical location | |
| Wallet & Blockchain | ||
| INVALID_ADDRESS | Provided blockchain address is not valid | |
| WALLET_NOT_FOUND | Referenced wallet does not exist in the system | |
| IN_USED_WALLET | Wallet is already associated with another operation | |
| DEPOSIT_ADDRESS_NOT_FOUND | No valid deposit address found for transaction | |
| TOKEN_WITHDRAWAL_DISABLED/TOKEN_DEPOSIT_DISABLED | Operations with specified token temporarily unavailable |
Security Considerations​
- Cookies are set with HttpOnly flag to prevent JavaScript access
- Secure flag ensures cookies are only sent over HTTPS connections
- SameSite policy protects against CSRF attacks
- Automatic token refresh mechanism maintains session validity
Best Practices​
- Always validate input data before sending requests
- Implement proper error handling
- Use appropriate caching strategies
- Follow rate limiting guidelines
- Leverage GraphQL's ability to request only the data you need
Support​
If you need help or encounter issues:
- Check our GitHub repository
- Contact our support team at support@blockbet.com