API Endpoints for Developers Building on FTM GAMES
For developers looking to integrate with or build upon the FTM GAMES ecosystem, the platform provides a comprehensive set of API endpoints. These endpoints are the fundamental building blocks that allow your applications to interact directly with the gaming platform’s core functionalities, including user management, in-game asset handling, blockchain transaction processing, and real-time gameplay data retrieval. The API is designed to be RESTful, using standard HTTP methods and returning data in JSON format, making it accessible for developers familiar with modern web development practices.
The primary base URL for all API requests is https://api.ftm-game.com/v1/. Authentication is a critical first step; you must obtain an API key from the FTM GAMES developer portal. This key is passed in the header of each request as Authorization: Bearer YOUR_API_KEY. Without valid authentication, all requests will return a 401 Unauthorized error. The API implements rate limiting to ensure stability, typically allowing for 1,000 requests per hour per API key, with specific endpoints potentially having lower limits to prevent abuse.
Core User and Authentication Endpoints
Managing user identity is the foundation of any gaming application. The authentication endpoints allow you to securely link your application’s users with their FTM GAMES profiles and wallets.
The POST /auth/login endpoint is used to initiate a user session. It typically requires a wallet address and a signature for verification, a common pattern in Web3 applications. Upon successful authentication, it returns a session token and basic user profile data. For user registration, POST /users creates a new user profile associated with a crypto wallet. The request body must include essential details like the user’s public wallet address and a chosen username. The response provides a unique user ID that you’ll use for all subsequent interactions related to that user.
To retrieve a user’s public profile information, such as their username, avatar, and join date, you would call GET /users/{user_id}. For a more detailed view, including private data like email (if provided) or linked social accounts, GET /users/{user_id}/profile is available but requires the user’s explicit permission scopes. Managing user sessions is done via POST /auth/logout, which invalidates the current session token.
| Endpoint | Method | Description | Key Parameters |
|---|---|---|---|
| /auth/login | POST | Authenticates a user via wallet signature. | wallet_address, signature |
| /users | POST | Registers a new user in the system. | username, wallet_address |
| /users/{id} | GET | Fetches public profile data for a user. | user_id (path parameter) |
| /auth/logout | POST | Terminates the current user session. | Requires auth header. |
In-Game Assets and NFT Management
Given the blockchain foundation of FTM GAMES, a significant portion of the API is dedicated to managing non-fungible tokens (NFTs) and other in-game assets. These endpoints allow you to query a user’s inventory, check the properties of specific items, and handle transfers.
The GET /users/{user_id}/assets endpoint is one of the most frequently used. It returns a paginated list of all NFTs owned by the user, such as characters, weapons, skins, or land parcels. Each asset in the response includes metadata like the token ID, contract address, name, description, and image URL. You can filter this list by asset type using a query parameter, for example, ?asset_type=character to only get character NFTs. To get the detailed attributes of a single asset, you use GET /assets/{contract_address}/{token_id}. This returns granular data, which could include stats for a weapon (e.g., damage, speed), traits for a character (e.g., rarity, level), or metadata for a cosmetic item.
For transactional actions, the API provides endpoints to prepare blockchain interactions. POST /assets/transfer is used to initiate a transfer of an asset from one user to another. It doesn’t execute the transaction on-chain directly but returns a signed transaction object that your application must then broadcast to the Fantom network using a library like Ethers.js or Web3.js. This two-step process enhances security. Similarly, POST /assets/mint handles the minting of new NFTs, often as a reward for gameplay achievements. This endpoint requires specific permissions and details about the asset to be created.
| Endpoint | Method | Description | Common Use Case |
|---|---|---|---|
| /users/{id}/assets | GET | Lists all assets owned by a user. | Displaying a player’s inventory. |
| /assets/{contract}/{id} | GET | Gets detailed metadata for a specific asset. | Showing stats for a weapon or character. |
| /assets/transfer | POST | Initiates an asset transfer between wallets. | Trading items between players. |
| /assets/mint | POST | Creates a new NFT asset. | Issuing rewards for completing a quest. |
Gameplay and Leaderboard Data
To create engaging experiences, you need access to real-time and historical gameplay data. These endpoints feed into features like leaderboards, player stats, and tournament results.
The GET /games endpoint provides a catalog of all available games on the platform. Each game object includes an ID, name, description, and relevant contract addresses. Once you have a game ID, you can fetch its leaderboard using GET /leaderboards/{game_id}. This endpoint supports sorting parameters like ?sort_by=score and ?order=desc, and it’s paginated to handle large datasets efficiently. The response includes the ranking, user ID, and the score or metric used for ranking.
For individual player statistics within a specific game, use GET /users/{user_id}/stats/{game_id}. This returns a rich dataset that can include metrics such as total matches played, win-loss ratio, highest score, average session length, and achievements unlocked. This data is invaluable for building personalized dashboards or matchmaking systems. Furthermore, the GET /matches/{match_id} endpoint allows you to retrieve the complete log of a specific match or game session. This is essential for developing replay features or for analytical purposes to understand gameplay patterns.
Economy and Token Utilities
The in-game economy is powered by the platform’s native utility token. The API provides endpoints to interact with token balances, staking mechanisms, and reward distributions.
Checking a user’s token balance is done via GET /users/{user_id}/balance. This returns the current balance of the native token, often denoted in the smallest unit (e.g., wei). For a historical view of transactions, GET /users/{user_id}/transactions lists deposits, withdrawals, and in-game purchases. You can filter this list by transaction type and date range.
Staking is a common mechanic for earning rewards. The GET /staking/{user_id} endpoint returns the user’s current staked amount, the duration of the stake, and the estimated rewards. To initiate a staking action, you would use POST /staking/stake, which, like asset transfers, returns a transaction object for on-chain execution. Similarly, POST /staking/unstake and POST /staking/claim handle the unstaking and reward claiming processes, respectively. These endpoints are crucial for building features that integrate deeply with the platform’s tokenomics.
Error Handling and Best Practices
Robust error handling is essential for a good developer experience. The FTM GAMES API uses conventional HTTP status codes. A 200 status indicates success, 400 signals a bad request (e.g., invalid parameters), 401 means unauthorized, 404 is for resources not found, and 429 indicates that you’ve exceeded the rate limit. The body of an error response includes a machine-readable code and a human-readable message to help with debugging.
When integrating, it’s a best practice to implement exponential backoff when you receive a 429 error. Always cache static data, like game metadata or asset properties, to reduce unnecessary API calls. For real-time data like leaderboards, consider the trade-off between freshness and performance, using appropriate cache expiration times. Thoroughly validate all user inputs before sending them to the API to prevent 400 errors. Finally, stay updated by monitoring the official developer documentation for any changes or additions to the API specification, as the platform is continuously evolving.