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.

Type Parameters

Hierarchy (view full)

Constructors

Properties

BACKEND_URL: string = ...
ConvertFunction: ((num) => T)

Type declaration

accessToken: string = ''
apiKey: undefined | string = process.env.BITBADGES_API_KEY
axios: AxiosInstance = ...

Methods

  • Broadcasts a transaction to the blockchain.

    Parameters

    • payload: string | BroadcastPostBody

    Returns Promise<BroadcastTxSuccessResponse>

    Remarks

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

    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.

    Parameters

    Returns Promise<CompleteClaimSuccessResponse>

    Remarks

    • API Route: POST /api/v0/claims/complete/:claimId/:cosmosAddress
    • 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);
  • Generates an Apple wallet pass for a code.

    Returns application/vnd.apple.pkpass content type.

    Returns Promise<GenerateAppleWalletPassSuccessResponse>

    Remarks

    • API Route: POST /api/v0/siwbbRequest/appleWalletPass
    • SDK Function Call: await BitBadgesApi.generateAppleWalletPass(payload);

    Example

    const res = await BitBadgesApi.generateAppleWalletPass(payload);
    console.log(res);

    Example

    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.

    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.

  • 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/:cosmosAddress
    • 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);
  • 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);
  • 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);
  • 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/:cosmosAddress
    • 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);
  • Simulates a transaction on the blockchain.

    Parameters

    • payload: string | BroadcastPostBody

    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.