Class BitBadgesAPI<T>

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.

import { BigIntify, Stringify, Numberify, BitBadgesAPI } from "bitbadgesjs-sdk";
const BitBadgesApi = new BitBadgesAPI({ convertFunction: BigIntify, ....})
const collections = await BitBadgesApi.getCollections(...);

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

Type Parameters

Hierarchy (view full)

Constructors

constructor

Properties

BACKEND_URL ConvertFunction accessToken apiKey appendedHeaders axios

Methods

addBalancesToOffChainStorage assertPositiveInteger broadcastTx calculatePoints checkIfSignedIn completeClaim createAddressLists createAttestation createClaims createGroup createSIWBBRequest deleteAddressLists deleteAttestation deleteClaims deleteGroup deleteSIWBBRequest exchangeSIWBBAuthorizationCode filterBadgesInCollection filterSuggestions getAccounts getAddressLists getAttestations getBadgeActivity getBadgeBalanceByAddress getBrowse getClaimAlerts getClaimAttemptStatus getClaims getCollections getDynamicDataActivity getDynamicDataBins getGatedContentForClaim getGroups getMapValues getMaps getOwnersForBadge getRefreshStatus getReservedClaimCodes getSIWBBRequestsForDeveloperApp getSearchResults getSignInChallenge getStatus handleApiError performBatchBinAction performBinAction refreshMetadata revokeOauthAuthorization rotateSIWBBRequest sendClaimAlert setAccessToken signOut simulateClaim simulateTx unsetAccessToken updateAccountInfo updateAddressLists updateAttestation updateClaims updateGroup updateUserSeenActivity verifyAttestation verifyOwnershipRequirements verifySIWBBRequest verifySignIn

Constructors

constructor

Properties

BACKEND_URL

BACKEND_URL: string = ...

ConvertFunction

ConvertFunction: ((num: NumberType) => T)

accessToken

accessToken: string = ''

apiKey

apiKey: undefined | string = process.env.BITBADGES_API_KEY

appendedHeaders

appendedHeaders: Record<string, string> = {}

axios

axios: AxiosInstance = ...

Methods

addBalancesToOffChainStorage

assertPositiveInteger

broadcastTx

calculatePoints

checkIfSignedIn

completeClaim

  • completeClaim(claimId, address, payload): Promise<CompleteClaimSuccessResponse>

  • 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.

    Parameters

    Returns Promise<CompleteClaimSuccessResponse>

    Remarks

    • API Route: POST /api/v0/claims/complete/:claimId/:address
    • SDK Function Call: await BitBadgesApi.completeClaim(claimId, address, { ...body });
    • Authentication: Must be signed in.

    Example

    const res = await BitBadgesApi.completeClaim(claimId, address, { ...body });
    console.log(res);

createAddressLists

createAttestation

createClaims

createGroup

createSIWBBRequest

deleteAddressLists

deleteAttestation

deleteClaims

deleteGroup

deleteSIWBBRequest

exchangeSIWBBAuthorizationCode

filterBadgesInCollection

filterSuggestions

getAccounts

  • getAccounts(payload): Promise<GetAccountsSuccessResponse<T>>

  • Gets accounts and accompying details.

    Parameters

    Returns Promise<GetAccountsSuccessResponse<T>>

    Remarks

    • API Route: POST /api/v0/users
    • SDK Function Call: await BitBadgesApi.getAccounts(payload);
    • Tutorial: See the Fetching Accounts tutoral on the official docs.
    • Authentication: Must be signed in, if fetching private information such as private lists or auth codes. If fetching public information only, no sign in required.

    Example

    const res = await BitBadgesApi.getAccounts([{ address, fetchSequence: true, fetchBalance: true }]);
    console.log(res);

    Note

    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.

getAddressLists

getAttestations

getBadgeActivity

getBadgeBalanceByAddress

getBrowse

getClaimAlerts

getClaimAttemptStatus

getClaims

getCollections

getDynamicDataActivity

getDynamicDataBins

getGatedContentForClaim

getGroups

getMapValues

getMaps

getOwnersForBadge

getRefreshStatus

getReservedClaimCodes

  • getReservedClaimCodes(claimId, address, payload): Promise<GetReservedClaimCodesSuccessResponse>

  • For on-chain claims where codes are "reserved" for a specific address, this function will return all codes reserved.

    Parameters

    Returns Promise<GetReservedClaimCodesSuccessResponse>

    Remarks

    • API Route: POST /api/v0/claims/reserved/:claimId/:address
    • SDK Function Call: await BitBadgesApi.getReservedClaimCodes(claimId, address, { ...body });
    • Authentication: Must be signed in.

    Example

    const res = await BitBadgesApi.getReservedClaimCodes(claimId, address, { ...body });
    console.log(res);

getSIWBBRequestsForDeveloperApp

getSearchResults

  • getSearchResults(searchValue, payload?): Promise<GetSearchSuccessResponse<T>>

  • Search collections, badges, accounts, address lists based on a search value.

    Parameters

    Returns Promise<GetSearchSuccessResponse<T>>

    Remarks

    • API Route: POST /api/v0/search/:searchValue
    • SDK Function Call: await BitBadgesApi.getSearchResults(searchValue);

    Example

    const res = await BitBadgesApi.getSearchResults('vitalik.eth', { noAddressLists: true, noCollections: true, noBadges: true });
    console.log(res);

getSignInChallenge

getStatus

handleApiError

performBatchBinAction

  • performBatchBinAction(payload, binId, binSecret, bodyAuth?): Promise<BatchBinActionSuccessResponse>

  • Performs multiple bin actions in batch.

    Parameters

    • payload: BatchBinActionPayload
    • binId: string
    • binSecret: string
    • bodyAuth: boolean = true

      There are two ways to pass in the payload.

      1. Body Auth: POST /api/v0/bin-actions/batch
      2. Path Auth: POST /api/v0/bin-actions/batch/{binId}/{binSecret}

      Since you are calling from the API and have control over the payload, we always recommend the body auth for more security.

    Returns Promise<BatchBinActionSuccessResponse>

    Remarks

    • API Route: POST /api/v0/bin-actions/batch/{binId}/{binSecret}
    • API Route (Body Auth): POST /api/v0/bin-actions/batch
    • SDK Function Call: await BitBadgesApi.performBatchBinAction(payload);
    • Authentication: Must be signed in.

performBinAction

  • performBinAction(payload, actionName, binId, binSecret, bodyAuth?): Promise<PerformBinActionSuccessResponse>

  • Performs a bin action.

    Parameters

    • payload: PerformBinActionPayload
    • actionName: string
    • binId: string
    • binSecret: string
    • bodyAuth: boolean = true

      There are two ways to pass in the payload.

      1. Body Auth: POST /api/v0/bin-actions/single
      2. Path Auth: POST /api/v0/bin-actions/{actionName}/{binId}/{binSecret}

      Since you are calling from the API and have control over the payload, we always recommend the body auth for more security.

    Returns Promise<PerformBinActionSuccessResponse>

    Remarks

    • API Route: POST /api/v0/bin-actions/{actionName}/{binId}/{binSecret}
    • API Route (Body Auth): POST /api/v0/bin-actions/single
    • SDK Function Call: await BitBadgesApi.performBinAction(payload);
    • Authentication: Must be signed in.

refreshMetadata

  • refreshMetadata(collectionId, payload?): Promise<RefreshMetadataSuccessResponse>

  • 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.

    Parameters

    Returns Promise<RefreshMetadataSuccessResponse>

    Remarks

    • API Route: POST /api/v0/collection/:collectionId/refresh
    • SDK Function Call: await BitBadgesApi.refreshMetadata(collectionId, payload);

    Example

    const res = await BitBadgesApi.refreshMetadata(collectionId);
    console.log(res);

revokeOauthAuthorization

rotateSIWBBRequest

sendClaimAlert

setAccessToken

signOut

simulateClaim

  • simulateClaim(claimId, address, payload): Promise<SimulateClaimSuccessResponse>

  • Simulates a claim attempt. A success response means the claim is valid and can be completed.

    Parameters

    Returns Promise<SimulateClaimSuccessResponse>

    Remarks

    • API Route: POST /api/v0/claims/simulate/:claimId/:address
    • SDK Function Call: await BitBadgesApi.simulateClaim(claimId, address, { ...body });
    • Authentication: Must be signed in.

    Example

    const res = await BitBadgesApi.simulateClaim(claimId, address, { ...body });
    console.log(res);

simulateTx

  • simulateTx(payload): Promise<SimulateTxSuccessResponse>

  • Simulates a transaction on the blockchain.

    Parameters

    Returns Promise<SimulateTxSuccessResponse>

    Remarks

    • API Route: POST /api/v0/simulate
    • SDK Function Call: await BitBadgesApi.simulateTx(payload);
    • Tutorial: See Broadcasting Transactions tutorial on the official docs.

    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.

unsetAccessToken

updateAccountInfo

updateAddressLists

updateAttestation

updateClaims

updateGroup

updateUserSeenActivity

verifyAttestation

verifyOwnershipRequirements

verifySIWBBRequest

verifySignIn

Settings

Member Visibility

On This Page

Constructors
Properties
Methods
addBalancesToOffChainStorageassertPositiveIntegerbroadcastTxcalculatePointscheckIfSignedIncompleteClaimcreateAddressListscreateAttestationcreateClaimscreateGroupcreateSIWBBRequestdeleteAddressListsdeleteAttestationdeleteClaimsdeleteGroupdeleteSIWBBRequestexchangeSIWBBAuthorizationCodefilterBadgesInCollectionfilterSuggestionsgetAccountsgetAddressListsgetAttestationsgetBadgeActivitygetBadgeBalanceByAddressgetBrowsegetClaimAlertsgetClaimAttemptStatusgetClaimsgetCollectionsgetDynamicDataActivitygetDynamicDataBinsgetGatedContentForClaimgetGroupsgetMapValuesgetMapsgetOwnersForBadgegetRefreshStatusgetReservedClaimCodesgetSIWBBRequestsForDeveloperAppgetSearchResultsgetSignInChallengegetStatushandleApiErrorperformBatchBinActionperformBinActionrefreshMetadatarevokeOauthAuthorizationrotateSIWBBRequestsendClaimAlertsetAccessTokensignOutsimulateClaimsimulateTxunsetAccessTokenupdateAccountInfoupdateAddressListsupdateAttestationupdateClaimsupdateGroupupdateUserSeenActivityverifyAttestationverifyOwnershipRequirementsverifySIWBBRequestverifySignIn