Adds approval details to off-chain storage.
POST /api/v0/addApprovalDetailsToOffChainStorageawait BitBadgesApi.addApprovalDetailsToOffChainStorage(requestBody);const res = await BitBadgesApi.addApprovalDetailsToOffChainStorage(requestBody);
console.log(res);
Adds a balance map to off-chain storage. Mode can either be 'ipfs" for storing on IPFS or 'centralized' for storing on DigitalOcean.
POST /api/v0/addBalancesToOffChainStorageawait BitBadgesApi.addBalancesToOffChainStorage(requestBody);const res = await BitBadgesApi.addBalancesToOffChainStorage(requestBody);
console.log(res);
Adds metadata to IPFS.
POST /api/v0/addMetadataToIpfsawait BitBadgesApi.addMetadataToIpfs(requestBody);const res = await BitBadgesApi.addMetadataToIpfs(requestBody);
console.log(res);
Adds a new review for a collection.
POST /api/v0/collection/:collectionId/addReviewawait BitBadgesApi.addReviewForCollection(collectionId, requestBody);const res = await BitBadgesApi.addReviewForCollection(collectionId, requestBody);
console.log(res);
Adds a review for a user.
POST /api/v0/user/:addressOrUsername/addReviewawait BitBadgesApi.addReviewForUser(addressOrUsername, requestBody);const res = await BitBadgesApi.addReviewForUser(addressOrUsername, requestBody);
console.log(res);
Broadcasts a transaction to the blockchain.
POST /api/v0/broadcastawait BitBadgesApi.broadcastTx(requestBody);Also, consider checking out Broadcast UI, so you can simply copy and paste your transaction to a UI. All signing, API communication, etc is outsourced to the UI.
For password based approvals, we hand out codes behind the scenes whenever a user requests a password. This is to prevent replay attacks on the blockchain. This API call will return a valid code if a valid password is provided.
Each address is limited to one code per password. If the password is provided again, they will receive the same code.
POST /api/v0/claims/:claimId/:cosmosAddressawait BitBadgesApi.checkAndCompleteClaim(collectionId, cid, password);const res = await BitBadgesApi.checkAndCompleteClaim(collectionId, cid, password);
console.log(res);
Checks if the user is signed in.
POST /api/v0/auth/statusawait BitBadgesApi.checkIfSignedIn(requestBody);Creates address lists stored by BitBadges centralized servers.
POST /api/v0/addressList/updateawait BitBadgesApi.updateAddressLists(requestBody);Must be created off-chain. For on-chain, they must be created through MsgCreateAddressMappings. Creator can update their created lists with no restrictions. Else, requires an edit key.
Creates a Blockin authentication code. This is used for signing in with Blockin at in-person events.
Optional requestBody: CreateBlockinAuthCodeRouteRequestBodyPOST /api/v0/authCode/createawait BitBadgesApi.createAuthCode(requestBody);Creates an off-chain secret signature (typically a credential).
POST /api/v0/secret/createawait BitBadgesApi.createSecret(requestBody);Deletes address lists. Must be created off-chain.
POST /api/v0/addressList/deleteawait BitBadgesApi.deleteAddressLists(requestBody);Deletes a Blockin authentication code. This is used for signing in with Blockin at in-person events.
Optional requestBody: DeleteBlockinAuthCodeRouteRequestBodyPOST /api/v0/authCode/deleteawait BitBadgesApi.deleteAuthCode(requestBody);Deletes a review.
Optional requestBody: DeleteReviewRouteRequestBodyPOST /api/v0/deleteReview/:reviewIdawait BitBadgesApi.deleteReview(reviewId, requestBody);const res = await BitBadgesApi.deleteReview(reviewId);
console.log(res);
Deletes an off-chain secret signature (typically a credential).
POST /api/v0/secret/deleteawait BitBadgesApi.deleteSecret(requestBody);Fetches arbitrary metadata directly from IPFS. This is useful for fetching metadata that is not stored on-chain.
POST /api/v0/metadataawait BitBadgesApi.fetchMetadataDirectly(requestBody);Filters badges in a collection based on multiple filter values.
POST /api/v0/filterBadgesInCollectionawait BitBadgesApi.filterBadgesInCollection(requestBody);Generates an Apple wallet pass for a code.
Returns application/vnd.apple.pkpass content type.
POST /api/v0/appleWalletPassawait BitBadgesApi.generateAppleWalletPass(requestBody);const res = await BitBadgesApi.generateAppleWalletPass(requestBody);
console.log(res);
const pass = Buffer.from(res.data);
const blob = new Blob([pass], { type: 'application/vnd.apple.pkpass' });
const url = window.URL.createObjectURL(blob);
if (url) {
const link = document.createElement('a');
link.href = url;
link.download = 'bitbadges.pkpass';
link.click()
}
Gets accounts and accompying details.
POST /api/v0/user/batchawait BitBadgesApi.getAccounts(requestBody);const res = await BitBadgesApi.getAccounts([{ address, fetchSequence: true, fetchBalance: true }]);
console.log(res);
This function is used to fetch accounts and their details. It is your responsibility to join the data together (paginations, etc). Use getAccountsAndUpdate for a more convenient way to handle paginations and appending metadata.
Gets address lists. Can be on-chain or off-chain.
POST /api/v0/addressListawait BitBadgesApi.getAddressLists(requestBody);Note for reserved lists, you can use getReservedAddressList from the SDK.
Gets a Blockin authentication code. This is used for signing in with Blockin at in-person events. Anyone with the signature is able to fetch the preimage message.
Optional requestBody: GetBlockinAuthCodeRouteRequestBodyPOST /api/v0/authCodeawait BitBadgesApi.getAuthCode(requestBody);Gets the activity for a specific badge in a collection
POST /api/v0/collection/:collectionId/:badgeId/activityawait BitBadgesApi.getBadgeActivity(collectionId, badgeId, requestBody);const res = await BitBadgesApi.getBadgeActivity(collectionId, badgeId, { bookmark: 'prev' });
console.log(res);
Gets the balance of a specific badge for a specific address
Optional requestBody: GetBadgeBalanceByAddressRouteRequestBodyPOST /api/v0/collection/:collectionId/balance/:cosmosAddressawait BitBadgesApi.getBadgeBalanceByAddress(collectionId, cosmosAddress);const res = await BitBadgesApi.getBadgeBalanceByAddress(collectionId, cosmosAddress);
console.log(res);
Gets details for a browse / explore page.
Optional requestBody: GetBrowseCollectionsRouteRequestBodyPOST /api/v0/browseawait BitBadgesApi.getBrowseCollections(requestBody);Gets claim alerts for a collection.
POST /api/v0/getClaimAlertsawait BitBadgesApi.getClaimAlerts(requestBody);Gets the claim by ID.
POST /api/v0/claimsawait BitBadgesApi.getClaims(requestBody);const res = await BitBadgesApi.getClaims(requestBody);
console.log(res);
This function retrieves badge collections and accompanying details. Consider using the getCollectionsAndUpdate function instead for native support in handling paginations, appending metadata, and more.
POST /api/v0/collection/batchconst res = await BitBadgesApi.getCollections([{ collectionId, metadataToFetch: { badgeIds: [{ start: 1n, end: 10n }] } }]);
const collection = res.collections[0];
Gets a key + timestamp pair for an API external call to prove it is actually coming from BitBadges.
POST /api/v0/externalCallKeyawait BitBadgesApi.getExternalCallKey(requestBody);Gets the follow details for a user with the BitBadges follow protocol.
POST /api/v0/getFollowDetailsawait BitBadgesApi.getFollowDetails(requestBody);Get maps by ID
POST /api/v0/mapsawait BitBadgesApi.getMaps(requestBody);Gets the owners for a specific badge in a collection
POST /api/v0/collection/:collectionId/:badgeId/ownersawait BitBadgesApi.getOwnersForBadge(collectionId, badgeId, requestBody);const res = await BitBadgesApi.getOwnersForBadge(collectionId, badgeId, { bookmark: 'prev' });
console.log(res);
Gets the refresh status for a collection. Used to track if any errors occur during a refresh, or if it is in the queue or not.
POST /api/v0/getRefreshStatusawait BitBadgesApi.getRefreshStatus(requestBody);Search collections, badges, accounts, address lists based on a search value.
Optional requestBody: GetSearchRouteRequestBodyPOST /api/v0/search/:searchValueawait BitBadgesApi.getSearchResults(searchValue);const res = await BitBadgesApi.getSearchResults('vitalik.eth', { noAddressLists: true, noCollections: true, noBadges: true });
console.log(res);
Get an off-chain secret signature (typically a credential).
POST /api/v0/secretawait BitBadgesApi.getSecret(requestBody);Gets the Blockin sign in challenge to be signed for authentication. The returned blockinMessage is the message to be signed by the user.
POST /api/v0/auth/getChallengeawait BitBadgesApi.getSignInChallenge(requestBody);const res = await BitBadgesApi.getSignInChallenge(requestBody);
console.log(res);
Gets the current status details about the blockchain / indexer (gas, block height, etc).
POST /api/v0/statusawait BitBadgesApi.getStatus();const res = await BitBadgesApi.getStatus();
console.log(res);
Gets the tokens from the faucet. This will only work on betanet.
Optional requestBody: GetTokensFromFaucetRouteRequestBodyPOST /api/v0/faucetawait BitBadgesApi.getTokensFromFaucet(requestBody);Triggers a metadata refresh for a specific collection. BitBadges API uses a refresh queue system for fetching anything off-chain. This will refetch any details for the collection (such as metadata, balances, approval details, etc). Note it will reject if recently refreshed. Uses a cooldown of 5 minutes.
Optional requestBody: RefreshMetadataRouteRequestBodyPOST /api/v0/collection/:collectionId/refreshawait BitBadgesApi.refreshMetadata(collectionId, requestBody);const res = await BitBadgesApi.refreshMetadata(collectionId);
console.log(res);
Sends claim alert notifications out.
POST /api/v0/sendClaimAlertsawait BitBadgesApi.sendClaimAlert(requestBody);Signs the user out.
Optional requestBody: SignOutRequestBodyPOST /api/v0/auth/logoutawait BitBadgesApi.signOut(requestBody);Simulates a transaction on the blockchain.
POST /api/v0/simulateawait BitBadgesApi.simulateTx(requestBody);This means that it will return the gas used and any errors that occur on a dry run. Should be used before broadcasting a transaction. Does not require signatures.
Updates the profile / account information for a user. We will only update the provided fields.
POST /api/v0/user/updateAccountawait BitBadgesApi.updateAccountInfo(requestBody);const res = await BitBadgesApi.updateAccountInfo(requestBody);
console.log(res);
Updates address lists stored by BitBadges centralized servers.
POST /api/v0/addressList/updateawait BitBadgesApi.updateAddressLists(requestBody);Must be created off-chain. For on-chain, they must be created through MsgCreateAddressMappings. Creator can update their created lists with no restrictions. Else, requires an edit key.
Update a secret.
POST /api/v0/user/secretsawait BitBadgesApi.updateUserSecrets(requestBody);Update Helper Functions for Pagination and Dynamic Fetches
Verifies the user signed challenge and grants them a valid session if everything checks out.
POST /api/v0/auth/verifyawait BitBadgesApi.verifySignIn(requestBody);const res = await BitBadgesApi.verifySignIn(requestBody);
console.log(res);
A generic route for verifying Blockin sign in requests. Used as a helper if implementing Blockin on your own.
POST /api/v0/auth/verifyGenericawait BitBadgesApi.verifySignInGeneric(requestBody);
This is the BitBadgesAPI class which provides all typed API calls to the BitBadges API. See official documentation for more details and examples. Must pass in a valid API key.
convertFunction is used to convert any responses returned by the API to your desired NumberType.
By default, we use the official API URL (https://api.bitbadges.io). You can override this by passing in a custom apiUrl.
See
BitBadges API Documentation