Accounts
Endpoints for managing user accounts and profiles
Retrieves an account by address or username.
const res = await BitBadgesApi.getAccount({ address: '...', username: '...' });
console.log(res);For more specific views, you can use the other routes.
SDK Links:
Authentication Details
Public Data: Available with API key only
Basic profile information
Etc
Private Data (requires user authentication):
Notification preferences
Stored Social connections
Etc
Scopes
readProfile- Required for private profile information like notification preferences, social connections, etc.
Couple Notes:
Note: The views and corresponding fields like tokensCollected, claimAlerts, etc will be blank with this simple GET but are provided in the response for compatibility with the SDK. To actually fetch these views, use the POST batch route or the individual view routes.
Authorizations
Query parameters
addressstringOptionalExample:
A native address is an address that is native to the user's chain. For example, an Ethereum address is native to Ethereum (0x...). If this type is used, we support any native address type. We do not require conversion to a BitBadges address like the BitBadgesAddress type.
0x...usernamestringOptional
Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
401
Unauthorized - Does not meet authentication requirements. This can be due to an invalid API key, CORS origin, or session cookie.
application/json
500
Internal Server Error
application/json
get
/userGET /api/v0/user HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Accept: */*
{
"account": {
"_docId": "text",
"_id": "text",
"publicKey": "AksB.... (base64)",
"accountNumber": 1,
"pubKeyType": "text",
"bitbadgesAddress": "bb1...",
"ethAddress": "0x...",
"btcAddress": "bc1...",
"thorAddress": "text",
"sequence": 1,
"balances": [
{
"amount": 1,
"denom": "text"
}
],
"fetchedProfile": "full",
"seenActivity": "1713301889",
"createdAt": "1713301889",
"discord": "text",
"twitter": "text",
"github": "text",
"telegram": "text",
"bluesky": "text",
"readme": "text",
"affiliateCode": "text",
"customLinks": [
{
"title": "text",
"url": "text",
"image": "https://example.com/image.png"
}
],
"hiddenBadges": [
{
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
}
],
"hiddenLists": [
"text"
],
"customPages": {
"badges": [
{
"title": "text",
"description": "Brief description.",
"items": [
{
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
}
]
}
],
"lists": [
{
"title": "text",
"description": "Brief description.",
"items": [
"text"
]
}
]
},
"watchlists": {
"badges": [
{
"title": "text",
"description": "Brief description.",
"items": [
{
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
}
]
}
],
"lists": [
{
"title": "text",
"description": "Brief description.",
"items": [
"text"
]
}
]
},
"profilePicUrl": "https://example.com",
"bannerImage": "https://example.com",
"username": "text",
"latestSignedInChain": "Bitcoin",
"notifications": {
"email": "text",
"discord": {
"id": "text",
"username": "text",
"discriminator": "text",
"token": "text"
},
"emailVerification": {
"verified": true,
"verifiedAt": "1713301889",
"token": "text",
"expiry": "1713301889",
"antiPhishingCode": "text"
},
"preferences": {
"listActivity": true,
"transferActivity": true,
"claimAlerts": true,
"claimActivity": true,
"ignoreIfInitiator": true
}
},
"socialConnections": {
"discord": {
"username": "text",
"id": "text",
"discriminator": "text",
"lastUpdated": "1713301889"
},
"twitter": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"google": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"github": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"twitch": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"strava": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"reddit": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"meetup": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"bluesky": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"mailchimp": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"facebook": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"googleCalendar": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"youtube": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"linkedIn": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"shopify": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"telegram": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"farcaster": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"slack": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
}
},
"publicSocialConnections": {
"discord": {
"username": "text",
"id": "text",
"discriminator": "text",
"lastUpdated": "1713301889"
},
"twitter": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"google": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"github": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"twitch": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"strava": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"reddit": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"meetup": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"bluesky": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"mailchimp": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"facebook": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"googleCalendar": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"youtube": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"linkedIn": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"shopify": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"telegram": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"farcaster": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"slack": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
}
},
"approvedSignInMethods": {
"discord": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"discriminator": "text",
"id": "text"
},
"github": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"google": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"twitter": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"facebook": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"addresses": [
{
"address": "0x...",
"scopes": [
{
"scopeName": "text",
"options": {}
}
]
}
],
"passwords": [
{
"passwordHash": "text",
"salt": "text",
"scopes": [
{
"scopeName": "text",
"options": {}
}
]
}
]
},
"resolvedName": "text",
"avatar": "text",
"solAddress": "6H2af6...",
"chain": "Bitcoin",
"airdropped": true,
"collected": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incomingApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"uri": "https://example.com",
"customData": "text",
"approvalCriteria": {
"coinTransfers": [
{
"to": "bb1...",
"coins": [
{
"amount": 1,
"denom": "text"
}
],
"overrideFromWithApproverAddress": true,
"overrideToWithInitiator": true
}
],
"merkleChallenges": [
{
"root": "text",
"expectedProofLength": 1,
"useCreatorAddressAsLeaf": true,
"maxUsesPerLeaf": 1,
"uri": "https://example.com",
"customData": "text",
"challengeTrackerId": "text",
"leafSigner": "text"
}
],
"mustOwnBadges": [
{
"collectionId": "text",
"amountRange": {
"start": 1,
"end": 1
},
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"overrideWithCurrentTime": true,
"mustSatisfyForAllAssets": true,
"ownershipCheckParty": "text"
}
],
"predeterminedBalances": {
"manualBalances": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
}
],
"incrementedBalances": {
"startBalances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incrementBadgeIdsBy": 1,
"incrementOwnershipTimesBy": 1,
"durationFromTimestamp": 1,
"allowOverrideTimestamp": true,
"recurringOwnershipTimes": {
"startTime": 1,
"intervalLength": 1,
"chargePeriodLength": 1
},
"allowOverrideWithAnyValidBadge": true
},
"orderCalculationMethod": {
"useOverallNumTransfers": true,
"usePerToAddressNumTransfers": true,
"usePerFromAddressNumTransfers": true,
"usePerInitiatedByAddressNumTransfers": true,
"useMerkleChallengeLeafIndex": true,
"challengeTrackerId": "text"
}
},
"approvalAmounts": {
"overallApprovalAmount": 1,
"perToAddressApprovalAmount": 1,
"perFromAddressApprovalAmount": 1,
"perInitiatedByAddressApprovalAmount": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"maxNumTransfers": {
"overallMaxNumTransfers": 1,
"perToAddressMaxNumTransfers": 1,
"perFromAddressMaxNumTransfers": 1,
"perInitiatedByAddressMaxNumTransfers": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"autoDeletionOptions": {
"afterOneUse": true,
"afterOverallMaxNumTransfers": true,
"allowCounterpartyPurge": true,
"allowPurgeIfExpired": true
},
"requireFromEqualsInitiatedBy": true,
"requireFromDoesNotEqualInitiatedBy": true,
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
],
"outgoingApprovals": [
{
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"uri": "https://example.com",
"customData": "text",
"approvalCriteria": {
"coinTransfers": [
{
"to": "bb1...",
"coins": [
{
"amount": 1,
"denom": "text"
}
],
"overrideFromWithApproverAddress": true,
"overrideToWithInitiator": true
}
],
"mustOwnBadges": [
{
"collectionId": "text",
"amountRange": {
"start": 1,
"end": 1
},
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"overrideWithCurrentTime": true,
"mustSatisfyForAllAssets": true,
"ownershipCheckParty": "text"
}
],
"merkleChallenges": [
{
"root": "text",
"expectedProofLength": 1,
"useCreatorAddressAsLeaf": true,
"maxUsesPerLeaf": 1,
"uri": "https://example.com",
"customData": "text",
"challengeTrackerId": "text",
"leafSigner": "text"
}
],
"predeterminedBalances": {
"manualBalances": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
}
],
"incrementedBalances": {
"startBalances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incrementBadgeIdsBy": 1,
"incrementOwnershipTimesBy": 1,
"durationFromTimestamp": 1,
"allowOverrideTimestamp": true,
"recurringOwnershipTimes": {
"startTime": 1,
"intervalLength": 1,
"chargePeriodLength": 1
},
"allowOverrideWithAnyValidBadge": true
},
"orderCalculationMethod": {
"useOverallNumTransfers": true,
"usePerToAddressNumTransfers": true,
"usePerFromAddressNumTransfers": true,
"usePerInitiatedByAddressNumTransfers": true,
"useMerkleChallengeLeafIndex": true,
"challengeTrackerId": "text"
}
},
"approvalAmounts": {
"overallApprovalAmount": 1,
"perToAddressApprovalAmount": 1,
"perFromAddressApprovalAmount": 1,
"perInitiatedByAddressApprovalAmount": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"maxNumTransfers": {
"overallMaxNumTransfers": 1,
"perToAddressMaxNumTransfers": 1,
"perFromAddressMaxNumTransfers": 1,
"perInitiatedByAddressMaxNumTransfers": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"requireToEqualsInitiatedBy": true,
"requireToDoesNotEqualInitiatedBy": true,
"autoDeletionOptions": {
"afterOneUse": true,
"afterOverallMaxNumTransfers": true,
"allowCounterpartyPurge": true,
"allowPurgeIfExpired": true
},
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
],
"userPermissions": {
"canUpdateOutgoingApprovals": [
{
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateIncomingApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveSelfInitiatedOutgoingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveSelfInitiatedIncomingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveAllIncomingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
},
"autoApproveSelfInitiatedOutgoingTransfers": true,
"autoApproveSelfInitiatedIncomingTransfers": true,
"autoApproveAllIncomingTransfers": true,
"_docId": "text",
"_id": "text",
"collectionId": "text",
"bitbadgesAddress": "bb1...",
"onChain": true,
"uri": "https://example.com",
"fetchedAt": "1713301889",
"fetchedAtBlock": 1,
"isPermanent": true,
"contentHash": "text",
"updateHistory": [
{
"txHash": "CE22D7...",
"block": 1,
"blockTimestamp": "1713301889",
"timestamp": "1713301889"
}
]
}
],
"activity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"to": [
"bb1..."
],
"from": "bb1...",
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"collectionId": "text",
"memo": "text",
"precalculateBalancesFromApproval": {
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
},
"prioritizedApprovals": [
{
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
}
],
"initiatedBy": "bb1...",
"txHash": "CE22D7...",
"precalculationOptions": {
"overrideTimestamp": 1,
"badgeIdsOverride": [
{
"start": 1,
"end": 1
}
]
},
"coinTransfers": [
{
"from": "bb1...",
"to": "bb1...",
"amount": 1,
"denom": "text",
"isProtocolFee": true
}
],
"approvalsUsed": [
{
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
}
],
"badgeId": 1,
"price": 1,
"volume": 1,
"denom": "text"
}
],
"listActivity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"listId": "customOrReservedListId",
"initiatedBy": "bb1...",
"addedToList": true,
"addresses": [
"bb1..."
],
"txHash": "CE22D7..."
}
],
"claimActivity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"success": true,
"claimId": "text",
"claimAttemptId": "text",
"bitbadgesAddress": "bb1...",
"claimType": "standalone"
}
],
"pointsActivity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"bitbadgesAddress": "bb1...",
"oldPoints": 1,
"newPoints": 1,
"applicationId": "text",
"pageId": "text"
}
],
"challengeTrackers": [
{
"_docId": "text",
"_id": "text",
"collectionId": "text",
"challengeTrackerId": "text",
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"usedLeafIndices": [
{
"leafIndex": 1,
"usedBy": "bb1..."
}
]
}
],
"approvalTrackers": [
{
"collectionId": "text",
"approvalId": "text",
"amountTrackerId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"trackerType": "text",
"approvedAddress": "bb1...",
"_docId": "text",
"_id": "text",
"numTransfers": 1,
"amounts": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"lastUpdatedAt": "1713301889"
}
],
"addressLists": [],
"claimAlerts": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"from": "text",
"bitbadgesAddresses": [
"bb1..."
],
"collectionId": "text",
"message": "text"
}
],
"siwbbRequests": [
{
"_docId": "text",
"_id": "text",
"code": "text",
"bitbadgesAddress": "bb1...",
"address": "0x...",
"chain": "Bitcoin",
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"expiresAt": "1713301889",
"createdAt": "1713301889",
"deletedAt": "1713301889",
"clientId": "text",
"redirectUri": "text",
"codeChallenge": "text",
"codeChallengeMethod": "S256"
}
],
"address": "0x...",
"nsfw": {
"reason": "text"
},
"reported": {
"reason": "text"
},
"views": {
"ANY_ADDITIONAL_PROPERTY": {
"ids": [
"text"
],
"type": "text",
"pagination": {
"bookmark": "text",
"hasMore": true
}
}
},
"alias": {
"collectionId": "text",
"listId": "customOrReservedListId"
},
"creatorCredits": {
"_docId": "text",
"_id": "text",
"credits": 1,
"creditsLimit": 1
}
}
}Retrieves accounts and accompanying details. This route is all-inclusive and uses a view-based approach to fetch specific data about the account. See more in the tutorial below.
const accountsRes = await BitBadgesApi.getAccounts({
accountsToFetch: [
{
//example
address: 'bb1...',
viewsToFetch: [
{
viewType: 'tokensCollected',
viewId: 'tokensCollected',
bookmark: '',
},
],
},
],
})
const account = accountsRes.accounts[0]Authentication Details
Public Data: Available with API key only
Basic profile information
Public balances
Public activity
Etc
Private Data (requires user authentication):
Notification preferences
Private Attestations
Private activity, etc
Etc
Scopes
readProfile- Required for private profile information like notification preferences, social connections, etc.readClaimAlerts- Required if fetching private claim alertsreadAuthenticationCodes- Required if fetching private authentication codes
Documentation References / Tutorials:
SDK Links:
Authorizations
Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Body
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
401
Unauthorized - Does not meet authentication requirements. This can be due to an invalid API key, CORS origin, or session cookie.
application/json
500
Internal Server Error
application/json
post
/usersPOST /api/v0/users HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 288
{
"accountsToFetch": [
{
"address": "0x...",
"username": "text",
"partialProfile": true,
"viewsToFetch": [
{
"viewId": "viewKey",
"viewType": "viewKey",
"specificCollections": [
{
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
}
],
"specificLists": [
"text"
],
"oldestFirst": true,
"bookmark": "text"
}
]
}
]
}{
"accounts": [
{
"_docId": "text",
"_id": "text",
"publicKey": "AksB.... (base64)",
"accountNumber": 1,
"pubKeyType": "text",
"bitbadgesAddress": "bb1...",
"ethAddress": "0x...",
"btcAddress": "bc1...",
"thorAddress": "text",
"sequence": 1,
"balances": [
{
"amount": 1,
"denom": "text"
}
],
"fetchedProfile": "full",
"seenActivity": "1713301889",
"createdAt": "1713301889",
"discord": "text",
"twitter": "text",
"github": "text",
"telegram": "text",
"bluesky": "text",
"readme": "text",
"affiliateCode": "text",
"customLinks": [
{
"title": "text",
"url": "text",
"image": "https://example.com/image.png"
}
],
"hiddenBadges": [
{
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
}
],
"hiddenLists": [
"text"
],
"customPages": {
"badges": [
{
"title": "text",
"description": "Brief description.",
"items": [
{
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
}
]
}
],
"lists": [
{
"title": "text",
"description": "Brief description.",
"items": [
"text"
]
}
]
},
"watchlists": {
"badges": [
{
"title": "text",
"description": "Brief description.",
"items": [
{
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
}
]
}
],
"lists": [
{
"title": "text",
"description": "Brief description.",
"items": [
"text"
]
}
]
},
"profilePicUrl": "https://example.com",
"bannerImage": "https://example.com",
"username": "text",
"latestSignedInChain": "Bitcoin",
"notifications": {
"email": "text",
"discord": {
"id": "text",
"username": "text",
"discriminator": "text",
"token": "text"
},
"emailVerification": {
"verified": true,
"verifiedAt": "1713301889",
"token": "text",
"expiry": "1713301889",
"antiPhishingCode": "text"
},
"preferences": {
"listActivity": true,
"transferActivity": true,
"claimAlerts": true,
"claimActivity": true,
"ignoreIfInitiator": true
}
},
"socialConnections": {
"discord": {
"username": "text",
"id": "text",
"discriminator": "text",
"lastUpdated": "1713301889"
},
"twitter": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"google": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"github": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"twitch": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"strava": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"reddit": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"meetup": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"bluesky": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"mailchimp": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"facebook": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"googleCalendar": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"youtube": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"linkedIn": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"shopify": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"telegram": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"farcaster": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"slack": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
}
},
"publicSocialConnections": {
"discord": {
"username": "text",
"id": "text",
"discriminator": "text",
"lastUpdated": "1713301889"
},
"twitter": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"google": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"github": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"twitch": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"strava": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"reddit": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"meetup": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"bluesky": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"mailchimp": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"facebook": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"googleCalendar": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"youtube": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"linkedIn": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"shopify": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"telegram": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"farcaster": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
},
"slack": {
"username": "text",
"id": "text",
"lastUpdated": "1713301889"
}
},
"approvedSignInMethods": {
"discord": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"discriminator": "text",
"id": "text"
},
"github": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"google": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"twitter": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"facebook": {
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"username": "text",
"id": "text"
},
"addresses": [
{
"address": "0x...",
"scopes": [
{
"scopeName": "text",
"options": {}
}
]
}
],
"passwords": [
{
"passwordHash": "text",
"salt": "text",
"scopes": [
{
"scopeName": "text",
"options": {}
}
]
}
]
},
"resolvedName": "text",
"avatar": "text",
"solAddress": "6H2af6...",
"chain": "Bitcoin",
"airdropped": true,
"collected": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incomingApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"uri": "https://example.com",
"customData": "text",
"approvalCriteria": {
"coinTransfers": [
{
"to": "bb1...",
"coins": [
{
"amount": 1,
"denom": "text"
}
],
"overrideFromWithApproverAddress": true,
"overrideToWithInitiator": true
}
],
"merkleChallenges": [
{
"root": "text",
"expectedProofLength": 1,
"useCreatorAddressAsLeaf": true,
"maxUsesPerLeaf": 1,
"uri": "https://example.com",
"customData": "text",
"challengeTrackerId": "text",
"leafSigner": "text"
}
],
"mustOwnBadges": [
{
"collectionId": "text",
"amountRange": {
"start": 1,
"end": 1
},
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"overrideWithCurrentTime": true,
"mustSatisfyForAllAssets": true,
"ownershipCheckParty": "text"
}
],
"predeterminedBalances": {
"manualBalances": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
}
],
"incrementedBalances": {
"startBalances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incrementBadgeIdsBy": 1,
"incrementOwnershipTimesBy": 1,
"durationFromTimestamp": 1,
"allowOverrideTimestamp": true,
"recurringOwnershipTimes": {
"startTime": 1,
"intervalLength": 1,
"chargePeriodLength": 1
},
"allowOverrideWithAnyValidBadge": true
},
"orderCalculationMethod": {
"useOverallNumTransfers": true,
"usePerToAddressNumTransfers": true,
"usePerFromAddressNumTransfers": true,
"usePerInitiatedByAddressNumTransfers": true,
"useMerkleChallengeLeafIndex": true,
"challengeTrackerId": "text"
}
},
"approvalAmounts": {
"overallApprovalAmount": 1,
"perToAddressApprovalAmount": 1,
"perFromAddressApprovalAmount": 1,
"perInitiatedByAddressApprovalAmount": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"maxNumTransfers": {
"overallMaxNumTransfers": 1,
"perToAddressMaxNumTransfers": 1,
"perFromAddressMaxNumTransfers": 1,
"perInitiatedByAddressMaxNumTransfers": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"autoDeletionOptions": {
"afterOneUse": true,
"afterOverallMaxNumTransfers": true,
"allowCounterpartyPurge": true,
"allowPurgeIfExpired": true
},
"requireFromEqualsInitiatedBy": true,
"requireFromDoesNotEqualInitiatedBy": true,
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
],
"outgoingApprovals": [
{
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"uri": "https://example.com",
"customData": "text",
"approvalCriteria": {
"coinTransfers": [
{
"to": "bb1...",
"coins": [
{
"amount": 1,
"denom": "text"
}
],
"overrideFromWithApproverAddress": true,
"overrideToWithInitiator": true
}
],
"mustOwnBadges": [
{
"collectionId": "text",
"amountRange": {
"start": 1,
"end": 1
},
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"overrideWithCurrentTime": true,
"mustSatisfyForAllAssets": true,
"ownershipCheckParty": "text"
}
],
"merkleChallenges": [
{
"root": "text",
"expectedProofLength": 1,
"useCreatorAddressAsLeaf": true,
"maxUsesPerLeaf": 1,
"uri": "https://example.com",
"customData": "text",
"challengeTrackerId": "text",
"leafSigner": "text"
}
],
"predeterminedBalances": {
"manualBalances": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
}
],
"incrementedBalances": {
"startBalances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incrementBadgeIdsBy": 1,
"incrementOwnershipTimesBy": 1,
"durationFromTimestamp": 1,
"allowOverrideTimestamp": true,
"recurringOwnershipTimes": {
"startTime": 1,
"intervalLength": 1,
"chargePeriodLength": 1
},
"allowOverrideWithAnyValidBadge": true
},
"orderCalculationMethod": {
"useOverallNumTransfers": true,
"usePerToAddressNumTransfers": true,
"usePerFromAddressNumTransfers": true,
"usePerInitiatedByAddressNumTransfers": true,
"useMerkleChallengeLeafIndex": true,
"challengeTrackerId": "text"
}
},
"approvalAmounts": {
"overallApprovalAmount": 1,
"perToAddressApprovalAmount": 1,
"perFromAddressApprovalAmount": 1,
"perInitiatedByAddressApprovalAmount": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"maxNumTransfers": {
"overallMaxNumTransfers": 1,
"perToAddressMaxNumTransfers": 1,
"perFromAddressMaxNumTransfers": 1,
"perInitiatedByAddressMaxNumTransfers": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"requireToEqualsInitiatedBy": true,
"requireToDoesNotEqualInitiatedBy": true,
"autoDeletionOptions": {
"afterOneUse": true,
"afterOverallMaxNumTransfers": true,
"allowCounterpartyPurge": true,
"allowPurgeIfExpired": true
},
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
],
"userPermissions": {
"canUpdateOutgoingApprovals": [
{
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateIncomingApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveSelfInitiatedOutgoingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveSelfInitiatedIncomingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveAllIncomingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
},
"autoApproveSelfInitiatedOutgoingTransfers": true,
"autoApproveSelfInitiatedIncomingTransfers": true,
"autoApproveAllIncomingTransfers": true,
"_docId": "text",
"_id": "text",
"collectionId": "text",
"bitbadgesAddress": "bb1...",
"onChain": true,
"uri": "https://example.com",
"fetchedAt": "1713301889",
"fetchedAtBlock": 1,
"isPermanent": true,
"contentHash": "text",
"updateHistory": [
{
"txHash": "CE22D7...",
"block": 1,
"blockTimestamp": "1713301889",
"timestamp": "1713301889"
}
]
}
],
"activity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"to": [
"bb1..."
],
"from": "bb1...",
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"collectionId": "text",
"memo": "text",
"precalculateBalancesFromApproval": {
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
},
"prioritizedApprovals": [
{
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
}
],
"initiatedBy": "bb1...",
"txHash": "CE22D7...",
"precalculationOptions": {
"overrideTimestamp": 1,
"badgeIdsOverride": [
{
"start": 1,
"end": 1
}
]
},
"coinTransfers": [
{
"from": "bb1...",
"to": "bb1...",
"amount": 1,
"denom": "text",
"isProtocolFee": true
}
],
"approvalsUsed": [
{
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
}
],
"badgeId": 1,
"price": 1,
"volume": 1,
"denom": "text"
}
],
"listActivity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"listId": "customOrReservedListId",
"initiatedBy": "bb1...",
"addedToList": true,
"addresses": [
"bb1..."
],
"txHash": "CE22D7..."
}
],
"claimActivity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"success": true,
"claimId": "text",
"claimAttemptId": "text",
"bitbadgesAddress": "bb1...",
"claimType": "standalone"
}
],
"pointsActivity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"bitbadgesAddress": "bb1...",
"oldPoints": 1,
"newPoints": 1,
"applicationId": "text",
"pageId": "text"
}
],
"challengeTrackers": [
{
"_docId": "text",
"_id": "text",
"collectionId": "text",
"challengeTrackerId": "text",
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"usedLeafIndices": [
{
"leafIndex": 1,
"usedBy": "bb1..."
}
]
}
],
"approvalTrackers": [
{
"collectionId": "text",
"approvalId": "text",
"amountTrackerId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"trackerType": "text",
"approvedAddress": "bb1...",
"_docId": "text",
"_id": "text",
"numTransfers": 1,
"amounts": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"lastUpdatedAt": "1713301889"
}
],
"addressLists": [],
"claimAlerts": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"from": "text",
"bitbadgesAddresses": [
"bb1..."
],
"collectionId": "text",
"message": "text"
}
],
"siwbbRequests": [
{
"_docId": "text",
"_id": "text",
"code": "text",
"bitbadgesAddress": "bb1...",
"address": "0x...",
"chain": "Bitcoin",
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"scopes": [
{
"scopeName": "text",
"options": {}
}
],
"expiresAt": "1713301889",
"createdAt": "1713301889",
"deletedAt": "1713301889",
"clientId": "text",
"redirectUri": "text",
"codeChallenge": "text",
"codeChallengeMethod": "S256"
}
],
"address": "0x...",
"nsfw": {
"reason": "text"
},
"reported": {
"reason": "text"
},
"views": {
"ANY_ADDITIONAL_PROPERTY": {
"ids": [
"text"
],
"type": "text",
"pagination": {
"bookmark": "text",
"hasMore": true
}
}
},
"alias": {
"collectionId": "text",
"listId": "customOrReservedListId"
},
"creatorCredits": {
"_docId": "text",
"_id": "text",
"credits": 1,
"creditsLimit": 1
}
}
]
}Gets address lists for a specific account. Specify the viewType to determine what address lists to retrieve.
await BitBadgesApi.getAddressListsForUser(address, { ... });SDK Links:
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
viewTypestring · enumOptionalExample:
The view type to search for. Default is 'all'
- 'all' will return all address lists the user is a member of (both on whitelist or on blacklist)
- 'created' will return all address lists the user has created
- 'whitelists' will return all address lists the user is on the whitelist of
- 'blacklists' will return all address lists the user is on the blacklist of
viewKeyPossible values: Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/listsGET /api/v0/account/{address}/lists HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"lists": []
}Gets Sign-In with BitBadges (SIWBB) requests for a user.
await BitBadgesApi.getSiwbbRequestsForUser({ address: "bb1..." });SDK Links:
Scopes:
readAuthenticationCodes- Required
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/requests/siwbbGET /api/v0/account/{address}/requests/siwbb HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"requests": []
}Gets transfer activity for a specific user.
await BitBadgesApi.getTransferActivityForUser({ address: "bb1..." });SDK Links:
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/activity/badgesGET /api/v0/account/{address}/activity/badges HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"activity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"to": [
"bb1..."
],
"from": "bb1...",
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"collectionId": "text",
"memo": "text",
"precalculateBalancesFromApproval": {
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
},
"prioritizedApprovals": [
{
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
}
],
"initiatedBy": "bb1...",
"txHash": "CE22D7...",
"precalculationOptions": {
"overrideTimestamp": 1,
"badgeIdsOverride": [
{
"start": 1,
"end": 1
}
]
},
"coinTransfers": [
{
"from": "bb1...",
"to": "bb1...",
"amount": 1,
"denom": "text",
"isProtocolFee": true
}
],
"approvalsUsed": [
{
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"version": 1
}
],
"badgeId": 1,
"price": 1,
"volume": 1,
"denom": "text"
}
]
}Gets tokens for a specific user. Specify the viewType to determine what tokens to retrieve. Default is 'collected'.
await BitBadgesApi.getBadgesViewForUser(address, { viewType: "collected" });SDK Links:
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
collectionIdstringOptional
Optional collection ID to filter by
viewTypestring · enumOptionalExample:
The view type to search for. Default is 'collected'
- 'collected' will return the tokens the user has a balance of
- 'managing' will return the tokens the user is managing
- 'created' will return the tokens the user has created
viewKeyPossible values: Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/badges/GET /api/v0/account/{address}/badges/ HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"badges": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incomingApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"uri": "https://example.com",
"customData": "text",
"approvalCriteria": {
"coinTransfers": [
{
"to": "bb1...",
"coins": [
{
"amount": 1,
"denom": "text"
}
],
"overrideFromWithApproverAddress": true,
"overrideToWithInitiator": true
}
],
"merkleChallenges": [
{
"root": "text",
"expectedProofLength": 1,
"useCreatorAddressAsLeaf": true,
"maxUsesPerLeaf": 1,
"uri": "https://example.com",
"customData": "text",
"challengeTrackerId": "text",
"leafSigner": "text"
}
],
"mustOwnBadges": [
{
"collectionId": "text",
"amountRange": {
"start": 1,
"end": 1
},
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"overrideWithCurrentTime": true,
"mustSatisfyForAllAssets": true,
"ownershipCheckParty": "text"
}
],
"predeterminedBalances": {
"manualBalances": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
}
],
"incrementedBalances": {
"startBalances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incrementBadgeIdsBy": 1,
"incrementOwnershipTimesBy": 1,
"durationFromTimestamp": 1,
"allowOverrideTimestamp": true,
"recurringOwnershipTimes": {
"startTime": 1,
"intervalLength": 1,
"chargePeriodLength": 1
},
"allowOverrideWithAnyValidBadge": true
},
"orderCalculationMethod": {
"useOverallNumTransfers": true,
"usePerToAddressNumTransfers": true,
"usePerFromAddressNumTransfers": true,
"usePerInitiatedByAddressNumTransfers": true,
"useMerkleChallengeLeafIndex": true,
"challengeTrackerId": "text"
}
},
"approvalAmounts": {
"overallApprovalAmount": 1,
"perToAddressApprovalAmount": 1,
"perFromAddressApprovalAmount": 1,
"perInitiatedByAddressApprovalAmount": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"maxNumTransfers": {
"overallMaxNumTransfers": 1,
"perToAddressMaxNumTransfers": 1,
"perFromAddressMaxNumTransfers": 1,
"perInitiatedByAddressMaxNumTransfers": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"autoDeletionOptions": {
"afterOneUse": true,
"afterOverallMaxNumTransfers": true,
"allowCounterpartyPurge": true,
"allowPurgeIfExpired": true
},
"requireFromEqualsInitiatedBy": true,
"requireFromDoesNotEqualInitiatedBy": true,
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
],
"outgoingApprovals": [
{
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"uri": "https://example.com",
"customData": "text",
"approvalCriteria": {
"coinTransfers": [
{
"to": "bb1...",
"coins": [
{
"amount": 1,
"denom": "text"
}
],
"overrideFromWithApproverAddress": true,
"overrideToWithInitiator": true
}
],
"mustOwnBadges": [
{
"collectionId": "text",
"amountRange": {
"start": 1,
"end": 1
},
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"overrideWithCurrentTime": true,
"mustSatisfyForAllAssets": true,
"ownershipCheckParty": "text"
}
],
"merkleChallenges": [
{
"root": "text",
"expectedProofLength": 1,
"useCreatorAddressAsLeaf": true,
"maxUsesPerLeaf": 1,
"uri": "https://example.com",
"customData": "text",
"challengeTrackerId": "text",
"leafSigner": "text"
}
],
"predeterminedBalances": {
"manualBalances": [
{
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
}
],
"incrementedBalances": {
"startBalances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"incrementBadgeIdsBy": 1,
"incrementOwnershipTimesBy": 1,
"durationFromTimestamp": 1,
"allowOverrideTimestamp": true,
"recurringOwnershipTimes": {
"startTime": 1,
"intervalLength": 1,
"chargePeriodLength": 1
},
"allowOverrideWithAnyValidBadge": true
},
"orderCalculationMethod": {
"useOverallNumTransfers": true,
"usePerToAddressNumTransfers": true,
"usePerFromAddressNumTransfers": true,
"usePerInitiatedByAddressNumTransfers": true,
"useMerkleChallengeLeafIndex": true,
"challengeTrackerId": "text"
}
},
"approvalAmounts": {
"overallApprovalAmount": 1,
"perToAddressApprovalAmount": 1,
"perFromAddressApprovalAmount": 1,
"perInitiatedByAddressApprovalAmount": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"maxNumTransfers": {
"overallMaxNumTransfers": 1,
"perToAddressMaxNumTransfers": 1,
"perFromAddressMaxNumTransfers": 1,
"perInitiatedByAddressMaxNumTransfers": 1,
"amountTrackerId": "text",
"resetTimeIntervals": {
"startTime": 1,
"intervalLength": 1
}
},
"requireToEqualsInitiatedBy": true,
"requireToDoesNotEqualInitiatedBy": true,
"autoDeletionOptions": {
"afterOneUse": true,
"afterOverallMaxNumTransfers": true,
"allowCounterpartyPurge": true,
"allowPurgeIfExpired": true
},
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
],
"userPermissions": {
"canUpdateOutgoingApprovals": [
{
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateIncomingApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"initiatedByListId": "customOrReservedListId",
"initiatedByList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"transferTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"approvalId": "text",
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveSelfInitiatedOutgoingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveSelfInitiatedIncomingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateAutoApproveAllIncomingTransfers": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
]
},
"autoApproveSelfInitiatedOutgoingTransfers": true,
"autoApproveSelfInitiatedIncomingTransfers": true,
"autoApproveAllIncomingTransfers": true,
"_docId": "text",
"_id": "text",
"collectionId": "text",
"bitbadgesAddress": "bb1...",
"onChain": true,
"uri": "https://example.com",
"fetchedAt": "1713301889",
"fetchedAtBlock": 1,
"isPermanent": true,
"contentHash": "text",
"updateHistory": [
{
"txHash": "CE22D7...",
"block": 1,
"blockTimestamp": "1713301889",
"timestamp": "1713301889"
}
]
}
]
}Gets lists activity for a specific user.
await BitBadgesApi.getListActivityForUser({ address: "bb1..." });SDK Links:
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/activity/listsGET /api/v0/account/{address}/activity/lists HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"listActivity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"listId": "customOrReservedListId",
"initiatedBy": "bb1...",
"addedToList": true,
"addresses": [
"bb1..."
],
"txHash": "CE22D7..."
}
]
}Gets claim activity for a specific user. Specify the viewType to determine what claim activity to retrieve.
Most claim activity will be public, but if the state is hidden, then only the manager of the claim and you should be able to see the activity.
await BitBadgesApi.getClaimActivityForUser(address, { ... });SDK Links:
Scopes:
completeClaims- Required if fetching all claim activity.
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
viewTypestring · enumOptionalExample:
The view type to search for. Default is 'public'
- 'all' will return all claim activity even private (must have permission to view private activity)
- 'public' will only return public claim activity
viewKeyPossible values: Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/activity/claimsGET /api/v0/account/{address}/activity/claims HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"activity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"success": true,
"claimId": "text",
"claimAttemptId": "text",
"bitbadgesAddress": "bb1...",
"claimType": "standalone"
}
]
}Gets points activity for a specific user.
await BitBadgesApi.getPointsActivityForUser({ address: "bb1..." });SDK Links:
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/activity/pointsGET /api/v0/account/{address}/activity/points HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"activity": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"bitbadgesAddress": "bb1...",
"oldPoints": 1,
"newPoints": 1,
"applicationId": "text",
"pageId": "text"
}
]
}Gets claim alerts for a specific user. Specify the viewType 'received' or 'sent' to determine what claim alerts to retrieve.
await BitBadgesApi.getClaimAlertsForUser(address, { viewType: 'received' });SDK Links:
Scopes:
readClaimAlerts- Required
Authorizations
Path parameters
addressstringRequired
Account address
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
viewTypestring · enumOptionalExample:
The view type to search for. Default is 'received'
- 'received' will return all claim alerts the user has received
- 'sent' will return all claim alerts the user has sent
viewKeyPossible values: Header parameters
x-api-keystringRequired
BitBadges API Key for authentication
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/account/{address}/claimAlertsGET /api/v0/account/{address}/claimAlerts HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"claimAlerts": [
{
"_docId": "text",
"_id": "text",
"timestamp": "1713301889",
"block": 1,
"_notificationsHandled": true,
"private": true,
"from": "text",
"bitbadgesAddresses": [
"bb1..."
],
"collectionId": "text",
"message": "text"
}
]
}Last updated