Token API Reference

The Token API provides functionality for interacting with cryptocurrency tokens on the BlockBet platform. It allows users to view token information, check balances, manage deposit addresses, handle withdrawals, and manage saved addresses.

Key Features

• Token information retrieval
• Balance checking
• Transaction history
• Deposit address generation
• Withdrawal processing
• Saved address management
• Bonus balance and history

Security

Most token operations require authentication through JWT tokens and authorization through role-based access control. Typically, operations require the USER role, ensuring that only authenticated users can perform token-related operations.

Some read-only operations, such as retrieving token information, can be accessed by both authenticated and anonymous users.

API Overview

Queries

The Token API provides the following queries:

Query	Description	Authentication
token(id: String!)	Get token by ID	Optional
tokens(ids: [String], search: String, limit: Int, includeZeroBalances: Boolean)	Get multiple tokens with filtering	Optional
tokenBySymbol(symbol: String!, chain: String, caseSensitive: Boolean)	Get token by symbol	Optional
balance(id: String!)	Get token balance	Required (USER)
bonusBalance(id: String!)	Get bonus balance for token	Required (USER)
totalBalance	Get total balance across all tokens	Required (USER)
allTokensActivities(page: Int, limit: Int, types: [String], fromDate: Date, toDate: Date, tokenIds: [String])	Get paginated token activities	Required (USER)
depositAddress(tokenId: String!, chain: String!)	Get deposit address for token	Required (USER)
savedAddresses(tokenId: String)	Get saved addresses	Required (USER)
bonusHistory(page: Int, limit: Int, filter: BonusHistoryFilterInput)	Get paginated bonus history	Required (USER)

Mutations

The Token API provides the following mutations:

Mutation	Description	Authentication
createSavedAddress(input: CreateSavedAddressInput!)	Create a saved address	Required (USER)
updateSavedAddress(id: String!, input: UpdateSavedAddressInput!)	Update a saved address	Required (USER)
deleteSavedAddress(id: String!)	Delete a saved address	Required (USER)
withdraw(input: WithdrawInput!)	Submit a withdrawal request	Required (USER)

Field Resolvers

The Token API provides the following field resolvers for the TokenModel:

Field	Description
price	Get current token price information
historicalDataByDays(days: Int!)	Get historical price data by days

Error Handling

The Token API handles errors by throwing appropriate exceptions, which are converted to GraphQL errors with status codes and messages. Common errors include:

• Authentication Errors: When the user is not authenticated
• Authorization Errors: When the user does not have the required role
• Validation Errors: When input data does not meet validation requirements
• Not Found Errors: When a requested resource does not exist
• Bad Request Errors: When a request cannot be processed due to invalid data
• Service Errors: When an external service (e.g., BadhombreAPI) fails

API Usage Examples

Get Token Information

query {
  token(id: "bitcoin") {
    id
    name
    symbol
    logoUri
    price {
      usd
      eur
      change24h
    }
    chains {
      chainName
      address
      minDepositAmount
      minWithdrawalAmount
    }
  }
}

Check Balance

query {
  balance(id: "bitcoin") {
    amount
    amountInFiat
  }
}

Get Total Balance

query {
  totalBalance {
    totalAmountInFiat
    tokens {
      id
      amount
      amountInFiat
    }
  }
}

Submit Withdrawal

mutation {
  withdraw(
    input: {
      tokenId: "bitcoin"
      chain: "BTC"
      address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh"
      amount: 0.1
    }
  )
}

Integration Notes

The Token API integrates with the BadhombreAPI for cryptocurrency operations, the TokenService for token data, and the UsersService for user data. It uses Redis for caching frequently accessed data like token prices and balances.