BitBadges Python SDK

Navigation

Verified details

These details have been verified by PyPI
Maintainers
Avatar for trevormil from gravatar.com trevormil

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Author: BitBadges
  • Requires: Python >=3.7
Classifiers
Report project as malware

Project description

bitbadgespy-sdk

Introduction

The BitBadges API is a RESTful API that enables developers to interact with the BitBadges blockchain and indexer. This API provides comprehensive access to the BitBadges ecosystem, allowing you to query and interact with digital badges, collections, accounts, blockchain data, and more. For complete documentation, see the BitBadges Documentation and use along with this reference.

Note: The API + documentation is new and may contain bugs. If you find any issues, please let us know via Discord or another contact method (https://bitbadges.io/contact).

Getting Started

Authentication

All API requests require an API key for authentication. You can obtain your API key from the BitBadges Developer Portal.

API Key Authentication

Include your API key in the x-api-key header:

x-api-key: your-api-key-here

User Authentication

Most read-only applications can function with just an API key. However, if you need to access private user data or perform actions on behalf of users, you have two options:

OAuth 2.0 (Sign In with BitBadges)

For performing actions on behalf of other users, use the standard OAuth 2.0 flow via Sign In with BitBadges. See the Sign In with BitBadges documentation for details.

You will pass the access token in the Authorization header:

Authorization: Bearer your-access-token-here

Password Self-Approve Method

For automating actions for your own account:

  1. Set up an approved password sign in in your account settings tab on https://bitbadges.io with desired scopes (e.g. completeClaims)
  2. Sign in using:
const { message } = await BitBadgesApi.getSignInChallenge(...);
const verificationRes = await BitBadgesApi.verifySignIn({
    message,
    signature: '', //Empty string
    password: '...'
})

Note: This method uses HTTP session cookies. Ensure your requests support credentials (e.g. axios: { withCredentials: true }).

Scopes

Note that for proper authentication, you must have the proper scopes set.

See https://bitbadges.io/auth/linkgen for a helper URL generation tool. The scopes will be included in the scope parameter of the SIWBB URL or set in your approved sign in settings.

Note that stuff marked as Full Access is typically reserved for the official site. If you think you may need this, contact us.

Available Scopes

  • Report (report) Report users or collections.

  • Read Profile (readProfile) Read your private profile information. This includes your email, approved sign-in methods, connections, and other private information.

  • Read Address Lists (readAddressLists) Read private address lists on behalf of the user.

  • Manage Address Lists (manageAddressLists) Create, update, and delete address lists on behalf of the user (private or public).

  • Manage Applications (manageApplications) Create, update, and delete applications on behalf of the user.

  • Manage Claims (manageClaims) Create, update, and delete claims on behalf of the user.

  • Manage Developer Apps (manageDeveloperApps) Create, update, and delete developer apps on behalf of the user.

  • Manage Dynamic Stores (manageDynamicStores) Create, update, and delete dynamic stores on behalf of the user.

  • Manage Utility Pages (manageUtilityPages) Create, update, and delete utility pages on behalf of the user.

  • Approve Sign In With BitBadges Requests (approveSignInWithBitBadgesRequests) Sign In with BitBadges on behalf of the user.

  • Read Authentication Codes (readAuthenticationCodes) Read Authentication Codes on behalf of the user.

  • Delete Authentication Codes (deleteAuthenticationCodes) Delete Authentication Codes on behalf of the user.

  • Send Claim Alerts (sendClaimAlerts) Send claim alerts on behalf of the user.

  • Read Claim Alerts (readClaimAlerts) Read claim alerts on behalf of the user. Note that claim alerts may contain sensitive information like claim codes, attestation IDs, etc.

  • Read Private Claim Data (readPrivateClaimData) Read private claim data on behalf of the user (e.g. codes, passwords, private user lists, etc.).

  • Complete Claims (completeClaims) Complete claims on behalf of the user.

  • Manage Off-Chain Balances (manageOffChainBalances) Manage off-chain balances on behalf of the user.

  • Embedded Wallet (embeddedWallet) Sign transactions on behalf of the user with their embedded wallet.


SDK Integration

The recommended way to interact with the API is through our TypeScript/JavaScript SDK:

import { BigIntify, BitBadgesAPI } from \"bitbadgesjs-sdk\";

// Initialize the API client
const api = new BitBadgesAPI({
  convertFunction: BigIntify,
  apiKey: 'your-api-key-here'
});

// Example: Fetch collections
const collections = await api.getCollections({
  collectionsToFetch: [{
    collectionId: 1n,
    metadataToFetch: {
      badgeIds: [{ start: 1n, end: 10n }]
    }
  }]
});

Tiers

There are 3 tiers of API keys, each with different rate limits and permissions. See the pricing page for more details: https://bitbadges.io/pricing

  • Free tier
  • Premium tier
  • Enterprise tier

Rate limit headers included in responses:

  • X-RateLimit-Limit: Total requests allowed per window
  • X-RateLimit-Remaining: Remaining requests in current window
  • X-RateLimit-Reset: Time until rate limit resets (UTC timestamp)

Response Formats

Error Response

All API errors follow a consistent format:

{
  // Serialized error object for debugging purposes
  // Advanced users can use this to debug issues
  error?: any;

  // UX-friendly error message that can be displayed to the user
  // Always present if error occurs
  errorMessage: string;

  // Authentication error flag
  // Present if the user is not authenticated
  unauthorized?: boolean;
}

Pagination

Cursor-based pagination is used for list endpoints:

{
  items: T[],
  bookmark: string, // Use this for the next page
  hasMore: boolean
}

Best Practices

  1. Rate Limiting: Implement proper rate limit handling
  2. Caching: Cache responses when appropriate
  3. Error Handling: Handle API errors gracefully
  4. Batch Operations: Use batch endpoints when possible

Additional Resources

Support

This Python package is automatically generated by the OpenAPI Generator project:

  • API version: 0.1
  • Package version: 0.1.66
  • Generator version: 7.12.0
  • Build package: org.openapitools.codegen.languages.PythonClientCodegen

Requirements.

Python 3.8+

Installation & Usage

pip install

If the python package is hosted on a repository, you can install directly using:

pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git

(you may need to run pip with root permission: sudo pip install git+https://github.com/GIT_USER_ID/GIT_REPO_ID.git)

Then import the package:

import bitbadgespy_sdk

Setuptools

Install via Setuptools.

python setup.py install --user

(or sudo python setup.py install to install the package for all users)

Then import the package:

import bitbadgespy_sdk

Tests

Execute pytest to run the tests.

Getting Started

Please follow the installation procedure and then run the following:

import bitbadgespy_sdk
from bitbadgespy_sdk.rest import ApiException
from pprint import pprint

# Defining the host is optional and defaults to https://api.bitbadges.io/api/v0
# See configuration.py for a list of all supported configuration parameters.
configuration = bitbadgespy_sdk.Configuration(
    host = "https://api.bitbadges.io/api/v0"
)

# The client must configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: apiKey
configuration.api_key['apiKey'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['apiKey'] = 'Bearer'


# Enter a context with an instance of the API client
with bitbadgespy_sdk.ApiClient(configuration) as api_client:
    # Create an instance of the API class
    api_instance = bitbadgespy_sdk.AccountsApi(api_client)
    x_api_key = 'x_api_key_example' # str | BitBadges API Key for authentication
    payload = bitbadgespy_sdk.IGetAccountPayload() # IGetAccountPayload | The payload for the request. Anything here should be specified as query parameters (e.g. ?key1=value1&key2=) (optional)

    try:
        # Get Account
        api_response = api_instance.get_account(x_api_key, payload=payload)
        print("The response of AccountsApi->get_account:\n")
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling AccountsApi->get_account: %s\n" % e)

Documentation for API Endpoints

All URIs are relative to https://api.bitbadges.io/api/v0

Class Method HTTP request Description
AccountsApi get_account GET /user Get Account
AccountsApi get_accounts POST /users Get Accounts - Batch
AccountsApi get_address_lists_for_user GET /account/{address}/lists Get Address Lists For User
AccountsApi get_badges_view_for_user GET /account/{address}/badges/ Get Badges For User
AccountsApi get_claim_activity_for_user GET /account/{address}/activity/claims Get Claim Activity For User
AccountsApi get_claim_alerts_for_user GET /account/{address}/claimAlerts Get Claim Alerts For User
AccountsApi get_list_activity_for_user GET /account/{address}/activity/lists Get Lists Activity For User
AccountsApi get_points_activity_for_user GET /account/{address}/activity/points Get Points Activity For User
AccountsApi get_siwbb_requests_for_user GET /account/{address}/requests/siwbb Get SIWBB Requests For User
AccountsApi get_transfer_activity_for_user GET /account/{address}/activity/badges Get Transfer Activity For User
AddressListsApi create_address_lists POST /addressLists Creates Address Lists
AddressListsApi delete_address_lists DELETE /addressLists Delete Address Lists
AddressListsApi get_address_list GET /addressList/{addressListId} Get Address List
AddressListsApi get_address_list_activity GET /addressLists/{addressListId}/activity Get Address List Activity
AddressListsApi get_address_list_claims GET /addressLists/{addressListId}/claims Get Address List Claims
AddressListsApi get_address_list_listings GET /addressLists/{addressListId}/listings Get Address List Listings
AddressListsApi get_address_lists POST /addressLists/fetch Get Address Lists - Batch
AddressListsApi update_address_list_addresses PUT /addressLists/addresses Update Address List Addresses
AddressListsApi update_address_list_core_details PUT /addressLists/coreDetails Update Address List Core Details
ApplicationsApi calculate_points POST /applications/points Calculate Points
ApplicationsApi create_application POST /applications Create Application
ApplicationsApi delete_application DELETE /applications Delete Application
ApplicationsApi get_application GET /application/{applicationId} Get Application
ApplicationsApi get_applications POST /applications/fetch Get Applications - Batch
ApplicationsApi get_points_activity GET /applications/points/activity Get Points Activity
ApplicationsApi search_applications GET /applications/search Search Applications
ApplicationsApi update_application PUT /applications Update Application
BadgesApi get_badge_activity GET /collection/{collectionId}/{badgeId}/activity Get Badge Activity
BadgesApi get_badge_balance_by_address GET /collection/{collectionId}/balance/{address} Get Badge Balances By Address
BadgesApi get_badge_balance_by_address_specific_badge GET /collection/{collectionId}/balance/{address}/{badgeId} Get Badge Balance By Address - Specific Badge
BadgesApi get_badge_metadata GET /collection/{collectionId}/{badgeId}/metadata Get Badge Metadata
BadgesApi get_collection GET /collection/{collectionId} Get Collection
BadgesApi get_collection_amount_tracker_by_id GET /api/v0/collection/amountTracker Get Collection Amount Tracker By ID
BadgesApi get_collection_amount_trackers GET /collection/{collectionId}/amountTrackers Get Collection Amount Trackers
BadgesApi get_collection_challenge_tracker_by_id GET /api/v0/collection/challengeTracker Get Collection Challenge Tracker By ID
BadgesApi get_collection_challenge_trackers GET /collection/{collectionId}/challengeTrackers Get Collection Challenge Trackers
BadgesApi get_collection_claims GET /collection/{collectionId}/claims Get Collection Claims
BadgesApi get_collection_listings GET /collection/{collectionId}/listings Get Collection Listings
BadgesApi get_collection_owners GET /collection/{collectionId}/owners Get Collection Owners
BadgesApi get_collection_transfer_activity GET /collection/{collectionId}/activity Get Collection Transfer Activity
BadgesApi get_collections_batch POST /collections Get Collections - Batch
BadgesApi get_owners_for_badge GET /collection/{collectionId}/{badgeId}/owners Get Badge Owners
BadgesApi get_refresh_status GET /collection/{collectionId}/refreshStatus Get Refresh Status
BadgesApi upload_balances POST /api/v0/uploadBalances Upload Balances
ClaimAlertsApi send_claim_alert POST /claimAlerts/send Sends Claim Alert
ClaimsApi check_claim_success GET /claims/success/{claimId}/{address} Check Claim Successes By User
ClaimsApi complete_claim POST /claims/complete/{claimId}/{address} Complete Claim
ClaimsApi create_claim POST /claims Create Claim
ClaimsApi delete_claim DELETE /claims Delete Claim
ClaimsApi generate_code GET /codes Get Code (Codes Plugin)
ClaimsApi get_attempt_data_from_request_bin GET /api/v0/requestBin/attemptData/{claimId}/{claimAttemptId} Get Attempt Data (Request Bin)
ClaimsApi get_claim GET /claim/{claimId} Get Claim
ClaimsApi get_claim_attempt_status GET /claims/status/{claimAttemptId} Get Claim Attempt Status
ClaimsApi get_claim_attempts GET /claims/{claimId}/attempts Get Claim Attempts
ClaimsApi get_claims POST /claims/fetch Get Claims - Batch
ClaimsApi get_gated_content_for_claim GET /claims/gatedContent/{claimId} Get Gated Content for Claim
ClaimsApi get_reserved_codes POST /claims/reserved/{claimId}/{address} Get Reserved Claim Codes
ClaimsApi search_claims GET /claims/search Search Claims
ClaimsApi simulate_claim POST /claims/simulate/{claimId}/{address} Simulate Claim
ClaimsApi update_claim PUT /claims Update Claim
DynamicStoresApi create_dynamic_data_store POST /dynamicStores Create Dynamic Data Store
DynamicStoresApi delete_dynamic_data_store DELETE /dynamicStores Delete Dynamic Data Store
DynamicStoresApi get_dynamic_data_activity GET /dynamicStores/activity Get Dynamic Data Activity
DynamicStoresApi get_dynamic_data_store GET /dynamicStore/{dynamicStoreId} Get Dynamic Data Store
DynamicStoresApi get_dynamic_data_store_value GET /dynamicStore/{dynamicStoreId}/value Get Dynamic Data Store Value
DynamicStoresApi get_dynamic_data_store_values_paginated GET /dynamicStore/{dynamicStoreId}/values Get Dynamic Data Store Values Paginated
DynamicStoresApi get_dynamic_data_stores POST /dynamicStores/fetch Fetch Dynamic Data Stores - Batch
DynamicStoresApi perform_store_action_batch_with_body_auth POST /storeActions/batch Perform Batch Store Actions (Body Auth)
DynamicStoresApi perform_store_action_single_with_body_auth POST /storeActions/single Perform Single Store Action (Body Auth)
DynamicStoresApi search_dynamic_data_stores GET /dynamicStores/search Search Dynamic Data Stores For User
DynamicStoresApi update_dynamic_data_store PUT /dynamicStores Update Dynamic Data Store
MapsAndProtocolsApi get_map GET /maps/{mapId} Get Map
MapsAndProtocolsApi get_map_value GET /mapValue/{mapId}/{key} Get Map Value
MapsAndProtocolsApi get_map_values POST /mapValues Get Map Values - Batch
MapsAndProtocolsApi get_maps POST /maps Get Maps - Batch
MiscellanousApi get_status GET /status Get Status
PluginsApi get_plugin GET /plugin/{pluginId} Get Plugin
PluginsApi get_plugins POST /plugins/fetch Get Plugins - Batch
PluginsApi search_plugins GET /plugins/search Search Plugins
SignInWithBitBadgesApi check_sign_in_status POST /auth/status Check Sign In Status
SignInWithBitBadgesApi create_developer_app POST /developerApps Create OAuth App
SignInWithBitBadgesApi create_siwbb_request POST /siwbbRequest Create SIWBB Request
SignInWithBitBadgesApi delete_developer_app DELETE /developerApps Delete OAuth App
SignInWithBitBadgesApi delete_siwbb_request DELETE /siwbbRequest Delete SIWBB Request
SignInWithBitBadgesApi exchange_siwbb_authorization_code POST /siwbb/token Exchange SIWBB Code
SignInWithBitBadgesApi generate_apple_wallet_pass POST /siwbbRequest/appleWalletPass Generate Apple Wallet Pass
SignInWithBitBadgesApi generate_google_wallet_pass POST /siwbbRequest/googleWalletPass Generate Google Wallet Pass
SignInWithBitBadgesApi get_developer_app GET /developerApp/{clientId} Get OAuth App
SignInWithBitBadgesApi get_siwbb_requests_for_developer_app GET /developerApps/siwbbRequests Get SIWBB Requests For Developer App
SignInWithBitBadgesApi revoke_oauth_authorization POST /siwbb/token/revoke Revoke Authorization
SignInWithBitBadgesApi rotate_siwbb_request POST /siwbbRequest/rotate Rotate SIWBB Request
SignInWithBitBadgesApi update_developer_app PUT /developerApps Update OAuth App
TransactionsApi broadcast_tx POST /broadcast Broadcast Transaction
TransactionsApi simulate_tx POST /simulate Simulate Transaction
UtilityPagesApi create_utility_page POST /utilityPages Create Utility Page
UtilityPagesApi delete_utility_page DELETE /utilityPages Delete Utility Page
UtilityPagesApi get_utility_page GET /utilityPage/{utilityPageId} Get Utility Page
UtilityPagesApi get_utility_pages POST /utilityPages/fetch Get Utility Pages - Batch
UtilityPagesApi search_utility_pages GET /utilityPages/search Search Utility Pages
UtilityPagesApi update_utility_page PUT /utilityPages Update Utility Page

Documentation For Models

Documentation For Authorization

Authentication schemes defined for the API:

apiKey

  • Type: API key
  • API key parameter name: x-api-key
  • Location: HTTP header

frontendOnly

  • Type: API key
  • API key parameter name: Origin
  • Location: HTTP header

userSignedIn

userMaybeSignedIn

userIsManager

userIsOwner

Author

Project details

Verified details

These details have been verified by PyPI
Maintainers
Avatar for trevormil from gravatar.com trevormil

Unverified details

These details have not been verified by PyPI
Project links
Meta
  • License: MIT License
  • Author: BitBadges
  • Requires: Python >=3.7
Classifiers

Release history Release notifications | RSS feed

0.1.88

0.1.87

0.1.86

0.1.85

0.1.84

0.1.83

0.1.82

0.1.81

0.1.80

0.1.79

0.1.78

0.1.77

0.1.76

0.1.75

0.1.74

0.1.73

0.1.72

0.1.71

0.1.70

0.1.69

0.1.68

0.1.67

This version

0.1.66

0.1.65

0.1.64

0.1.63

0.1.62

0.1.61

0.1.60

0.1.59

0.1.58

0.1.57

0.1.56

0.1.55

0.1.54

0.1.53

0.1.52

0.1.51

0.1.50

0.1.49

0.1.48

0.1.47

0.1.46

0.1.45

0.1.44

0.1.43

0.1.42

0.1.41

0.1.40

0.1.39

0.1.38

0.1.37

0.1.36

0.1.35

0.1.34

0.1.33

0.1.32

0.1.31

0.1.30

0.1.29

0.1.28

0.1.27

0.1.26

0.1.25

0.1.24

0.1.23

0.1.22

0.1.21

0.1.20

0.1.19

0.1.18

0.1.17

0.1.16

0.1.15

0.1.14

0.1.13

0.1.12

0.1.11

0.1.10

0.1.9

0.1.8

0.1.7

0.1.3

0.1.2

0.1.1

0.1.0

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

bitbadgespy_sdk-0.1.66.tar.gz (600.9 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

bitbadgespy_sdk-0.1.66-py3-none-any.whl (4.9 MB view details)

Uploaded Python 3

File details

Details for the file bitbadgespy_sdk-0.1.66.tar.gz.

File metadata

  • Download URL: bitbadgespy_sdk-0.1.66.tar.gz
  • Upload date:
  • Size: 600.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.1.0 CPython/3.12.3

File hashes

Hashes for bitbadgespy_sdk-0.1.66.tar.gz
Algorithm Hash digest
SHA256 7906ebc344bd861be22b7da7170346dda1ce2d03c63cf967616b853e8129185b
MD5 85e0258fad1489762d8eb3484f7d6f3f
BLAKE2b-256 eddffc53edc03fb899dc42e992c40d527ec4d4a1dc1531c10616468c86e99198

See more details on using hashes here.

File details

Details for the file bitbadgespy_sdk-0.1.66-py3-none-any.whl.

File metadata

File hashes

Hashes for bitbadgespy_sdk-0.1.66-py3-none-any.whl
Algorithm Hash digest
SHA256 786692a61662a80956095a4c9b38821005dbcf7cbbc87f802b9ae78a10684c06
MD5 70af88d0fe2cd2f4b33328d1c5a5cb4f
BLAKE2b-256 5c84f85242173878dd396bb5cd727a41ee431454735efe1958969e3822396b9b

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page