API
Getting Started
Get an API key by going to https://bitbadges.io/developer. Keys expire after one year, but it is recommended that you rotate them even more often than that.
Start sending requests to the base URL of https://api.bitbadges.io/ with the HTTP header x-api-key. All routes require an API key.
Status Codes
We use standard HTTP error codes. 200 is the success code. All errors should follow the ErrorResponse type.
Pre-Readings
We recommend reading all concepts for background information. Also visit the Tutorials for common execution flows.
Number Types / Stringified Responses
All requests / responses are stringified before being sent over HTTP. This is to avoid losing precision with big numbers > JavaScript's MAX_SAFE_INTEGER. For how to convert the responses to your desired NumberType (bigint, JS number, etc), please see Number Type Conversions from the SDK.
We recommend using the JavaScript bigint type.
Note: this is all handled for you if you use the BitBadges API SDK.
Quickstart
See the quickstart repo for a fully configured example repository with fetching collections, accounts, and more with the API!
Routes
See all documentation for routes here.
pageRoutesUsing the API SDK (Recommended)
If you are using JavaScript / TypeScript, consider using the typed API SDK for convenience. This will give you typed routes, provide quality checks, and also auto-convert all responses to your desired number type (bigint, Number, etc).
Check out https://github.com/BitBadges/bitbadges-frontend/blob/main/src/bitbadges-api/api.ts for a working reference of the API routes using the SDK.
Using BitBadges JS/SDK
Check out the BitBadges JS/SDK for implementing further functionality beyond just API requests / responses, such as manipulating balances, handling approvals, checking permissions, etc.
⚒️pageBitBadges JS / SDKAuthentication
For most applications, you should be fine without needing to access private user authenticated information. This is typically only needed by the official BitBadges frontend.
If the user is not signed in and requests private information, the API will respond with a 401 error code. See Authentication for how to authenticate users.
Confined Responses
IMPORTANT: Remember that each retrieval is confined to what is stipulated in the query options. It is your responsibility to append the data to your previous responses as you need. The Tutorials and Concepts will be extremely beneficial to help you deal with this.
Bookmarking
Throughout the API, we use a bookmark technique. For the first request, you will not need to specify a bookmark (e.g. ""), and it will fetch the first page. Within the response, it will return a bookmark and hasMore. hasMore defines whether there are more pages to be fetched. To fetch the next page, you will specify the returned bookmark from the previous request to the next request. This process can be repeated until all are loaded.
Tutorials
pageTutorialsLast updated