Tokens
Endpoints for token and collection operations
Gets a specific collection.
await BitBadgesApi.getCollection("123", { ... });SDK Links:
Note: The views and corresponding fields like owners, approvalTrackers, 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
Path parameters
collectionIdstringRequired
Collection ID
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
/collection/{collectionId}GET /api/v0/collection/{collectionId} HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"collection": {
"_docId": "text",
"_id": "text",
"collectionId": "text",
"collectionMetadataTimeline": {
"0": {
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"collectionMetadata": {
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"uri": "https://example.com",
"fetchedUri": "text",
"customData": "text",
"toUploadToIpfs": true
}
}
},
"badgeMetadataTimeline": {
"0": {
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeMetadata": [
{
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"uri": "https://example.com",
"fetchedUri": "text",
"customData": "text",
"toUploadToIpfs": true
}
]
}
},
"customDataTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"customData": "text"
}
],
"managerTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"manager": "bb1..."
}
],
"collectionApprovals": {
"0": {
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"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
},
"requireToEqualsInitiatedBy": true,
"requireFromEqualsInitiatedBy": true,
"requireToDoesNotEqualInitiatedBy": true,
"requireFromDoesNotEqualInitiatedBy": true,
"overridesFromOutgoingApprovals": true,
"overridesToIncomingApprovals": true,
"userRoyalties": {
"percentage": 1,
"payoutAddress": "text"
},
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
},
"standardsTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"standards": [
"text"
]
}
],
"isArchivedTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"isArchived": true
}
],
"createdBy": "bb1...",
"createdBlock": 1,
"createdTimestamp": "1713301889",
"updateHistory": [
{
"txHash": "CE22D7...",
"block": 1,
"blockTimestamp": "1713301889",
"timestamp": "1713301889"
}
],
"validBadgeIds": [
{
"start": 1,
"end": 1
}
],
"mintEscrowAddress": "text",
"cosmosCoinWrapperPaths": {
"0": {
"address": "text",
"denom": "text",
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"symbol": "text",
"denomUnits": [
{
"decimals": 1,
"symbol": "text",
"isDefaultDisplay": true
}
],
"allowOverrideWithAnyValidToken": true,
"allowCosmosWrapping": true
}
},
"invariants": {
"noCustomOwnershipTimes": true,
"maxSupplyPerId": 1
},
"collectionPermissions": {
"canDeleteCollection": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canArchiveCollection": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateStandards": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateCustomData": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateManager": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateCollectionMetadata": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateValidBadgeIds": [
{
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateBadgeMetadata": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateCollectionApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"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"
}
]
}
]
},
"defaultBalances": {
"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
},
"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"
}
],
"owners": [
{
"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"
}
]
}
],
"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"
}
],
"listings": [
{
"_docId": "text",
"_id": "text",
"listingId": "text",
"type": "text",
"createdBy": "bb1...",
"managedBy": "bb1...",
"directLink": "text",
"createdAt": "1713301889",
"lastUpdated": "1713301889",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"inheritMetadataFrom": {
"claimId": "text",
"applicationId": "text",
"collectionId": "text",
"listId": "customOrReservedListId",
"mapId": "text",
"badgeId": "text"
},
"content": [
{
"type": "text",
"label": "text",
"content": "text"
}
],
"links": [
{
"url": "text",
"claimId": "text",
"applicationId": "text",
"collectionId": "text",
"listId": "customOrReservedListId",
"mapId": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
}
}
],
"displayTimes": {
"start": 1,
"end": 1
},
"visibility": "public",
"categories": [
"text"
],
"approvalStatus": {
"isApproved": true,
"isFeatured": true,
"featuredPriority": 1,
"rejected": true,
"reason": "text",
"updatedBy": "bb1..."
},
"viewCount": 1,
"estimatedCost": {
"amount": 1,
"denom": "text"
},
"estimatedTime": "text",
"viewsByPeriod": {
"hourly": 1,
"daily": 1,
"weekly": 1,
"monthly": 1
},
"linkedTo": {
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"listId": "customOrReservedListId"
},
"locale": "text",
"homePageView": {
"type": "badges",
"category": "text"
}
}
],
"nsfw": {
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"reason": "text"
},
"reported": {
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"reason": "text"
},
"views": {
"ANY_ADDITIONAL_PROPERTY": {
"ids": [
"text"
],
"type": "text",
"pagination": {
"bookmark": "text",
"hasMore": true
}
}
},
"claims": [
{
"_includesPrivateParams": true,
"claimId": "text",
"createdBy": "bb1...",
"managedBy": "bb1...",
"collectionId": "text",
"standaloneClaim": true,
"listId": "customOrReservedListId",
"trackerDetails": {
"collectionId": "text",
"approvalId": "text",
"challengeTrackerId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1..."
},
"balancesToSet": {
"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"
}
},
"plugins": [
{
"instanceId": "text",
"pluginId": 1,
"version": "text",
"publicParams": null,
"privateParams": null,
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png"
},
"publicState": null,
"privateState": null
}
],
"rewards": [
{
"rewardId": "text",
"instanceId": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png"
},
"automatic": true,
"gatedContent": {
"content": "text",
"url": "text",
"params": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"calculationMethod": {
"alwaysShow": true,
"minClaimSuccesses": 1
}
}
],
"estimatedCost": "text",
"showInSearchResults": true,
"categories": [
"text"
],
"estimatedTime": "text",
"manualDistribution": true,
"approach": "text",
"seedCode": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"assignMethod": "text",
"lastUpdated": 1,
"version": 1,
"satisfyMethod": {
"type": "AND",
"conditions": [
"text"
],
"options": {
"minNumSatisfied": 1
}
},
"cachePolicy": {
"ttl": 1,
"alwaysPermanent": true,
"permanentAfter": "1713301889"
},
"_templateInfo": {
"supportedApproaches": [
"text"
],
"pluginId": "text",
"completedTemplateStep": true
}
}
],
"stats": {
"_docId": "text",
"_id": "text",
"overallVolume": [
{
"amount": 1,
"denom": "text"
}
],
"dailyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"weeklyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"monthlyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"yearlyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"lastUpdatedAt": "1713301889",
"collectionId": "text",
"floorPrices": [
{
"amount": 1,
"denom": "text"
}
],
"uniqueOwners": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"floorPriceHistory": [
{
"floorPrice": {
"amount": 1,
"denom": "text"
},
"updatedAt": "1713301889"
}
],
"payoutRewards": [
{
"amount": 1,
"denom": "text"
}
]
},
"badgeFloorPrices": [
{
"_docId": "text",
"_id": "text",
"collectionId": "text",
"badgeId": 1,
"floorPrices": [
{
"amount": 1,
"denom": "text"
}
],
"floorPriceHistory": [
{
"floorPrice": {
"amount": 1,
"denom": "text"
},
"updatedAt": "1713301889"
}
]
}
]
},
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
}
}Gets current metadata for a specific token in a collection.
await BitBadgesApi.getBadgeMetadata("123", "1");SDK Links:
Authorizations
Path parameters
collectionIdstringRequired
Collection ID
badgeIdstringRequired
Token ID
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
/collection/{collectionId}/{badgeId}/metadataGET /api/v0/collection/{collectionId}/{badgeId}/metadata HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
}
}Retrieves collections and associated details. This route is all-inclusive and uses a view-based approach to fetch specific data about collections, including metadata, balances, owners, and more.
const res = await BitBadgesApi.getCollections({
collectionsToFetch: [
{
collectionId: 1n,
metadataToFetch: {
badgeIds: [{ start: 1n, end: 10n }],
},
fetchTotalAndMintBalances: true,
viewsToFetch: [
{
viewType: 'owners',
viewId: 'owners',
bookmark: '',
},
],
},
],
})
const collection = res.collections[0]Scopes:
readPrivateClaimData- Required if fetching private claim data (must also be the manager)
Documentation References / Tutorials:
SDK Links:
Note: This route has lots of legacy features that are planned to be deprecated. For any views, we recommend using the other GET routes.
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
/collectionsPOST /api/v0/collections HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 749
{
"collectionsToFetch": [
{
"viewsToFetch": [
{
"viewType": "viewKey",
"viewId": "viewKey",
"bookmark": "text",
"oldestFirst": true,
"address": "text",
"badgeId": 1
}
],
"fetchTotalBalances": true,
"challengeTrackersToFetch": [
{
"collectionId": "text",
"approvalId": "text",
"challengeTrackerId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1..."
}
],
"disableDefaults": true,
"approvalTrackersToFetch": [
{
"collectionId": "text",
"approvalId": "text",
"amountTrackerId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"trackerType": "text",
"approvedAddress": "bb1..."
}
],
"fetchPrivateParams": true,
"metadataToFetch": {
"doNotFetchCollectionMetadata": true,
"uris": [
"text"
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
]
},
"badgeFloorPricesToFetch": "text",
"collectionId": "text"
}
]
}{
"collections": [
{
"_docId": "text",
"_id": "text",
"collectionId": "text",
"collectionMetadataTimeline": {
"0": {
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"collectionMetadata": {
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"uri": "https://example.com",
"fetchedUri": "text",
"customData": "text",
"toUploadToIpfs": true
}
}
},
"badgeMetadataTimeline": {
"0": {
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeMetadata": [
{
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"uri": "https://example.com",
"fetchedUri": "text",
"customData": "text",
"toUploadToIpfs": true
}
]
}
},
"customDataTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"customData": "text"
}
],
"managerTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"manager": "bb1..."
}
],
"collectionApprovals": {
"0": {
"toListId": "customOrReservedListId",
"toList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"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
},
"requireToEqualsInitiatedBy": true,
"requireFromEqualsInitiatedBy": true,
"requireToDoesNotEqualInitiatedBy": true,
"requireFromDoesNotEqualInitiatedBy": true,
"overridesFromOutgoingApprovals": true,
"overridesToIncomingApprovals": true,
"userRoyalties": {
"percentage": 1,
"payoutAddress": "text"
},
"dynamicStoreChallenges": [
{
"storeId": 1
}
],
"ethSignatureChallenges": [
{
"signer": "0x...",
"challengeTrackerId": "text",
"uri": "https://example.com",
"customData": "text"
}
]
},
"version": 1
}
},
"standardsTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"standards": [
"text"
]
}
],
"isArchivedTimeline": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"isArchived": true
}
],
"createdBy": "bb1...",
"createdBlock": 1,
"createdTimestamp": "1713301889",
"updateHistory": [
{
"txHash": "CE22D7...",
"block": 1,
"blockTimestamp": "1713301889",
"timestamp": "1713301889"
}
],
"validBadgeIds": [
{
"start": 1,
"end": 1
}
],
"mintEscrowAddress": "text",
"cosmosCoinWrapperPaths": {
"0": {
"address": "text",
"denom": "text",
"balances": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"symbol": "text",
"denomUnits": [
{
"decimals": 1,
"symbol": "text",
"isDefaultDisplay": true
}
],
"allowOverrideWithAnyValidToken": true,
"allowCosmosWrapping": true
}
},
"invariants": {
"noCustomOwnershipTimes": true,
"maxSupplyPerId": 1
},
"collectionPermissions": {
"canDeleteCollection": [
{
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canArchiveCollection": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateStandards": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateCustomData": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateManager": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateCollectionMetadata": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateValidBadgeIds": [
{
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateBadgeMetadata": [
{
"timelineTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"permanentlyPermittedTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
],
"permanentlyForbiddenTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"canUpdateCollectionApprovals": [
{
"fromListId": "customOrReservedListId",
"fromList": {
"listId": "customOrReservedListId",
"addresses": [
"text"
],
"whitelist": true,
"uri": "https://example.com",
"customData": "text",
"createdBy": "bb1..."
},
"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"
}
]
}
]
},
"defaultBalances": {
"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
},
"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"
}
],
"owners": [
{
"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"
}
]
}
],
"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"
}
],
"listings": [
{
"_docId": "text",
"_id": "text",
"listingId": "text",
"type": "text",
"createdBy": "bb1...",
"managedBy": "bb1...",
"directLink": "text",
"createdAt": "1713301889",
"lastUpdated": "1713301889",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"inheritMetadataFrom": {
"claimId": "text",
"applicationId": "text",
"collectionId": "text",
"listId": "customOrReservedListId",
"mapId": "text",
"badgeId": "text"
},
"content": [
{
"type": "text",
"label": "text",
"content": "text"
}
],
"links": [
{
"url": "text",
"claimId": "text",
"applicationId": "text",
"collectionId": "text",
"listId": "customOrReservedListId",
"mapId": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
}
}
],
"displayTimes": {
"start": 1,
"end": 1
},
"visibility": "public",
"categories": [
"text"
],
"approvalStatus": {
"isApproved": true,
"isFeatured": true,
"featuredPriority": 1,
"rejected": true,
"reason": "text",
"updatedBy": "bb1..."
},
"viewCount": 1,
"estimatedCost": {
"amount": 1,
"denom": "text"
},
"estimatedTime": "text",
"viewsByPeriod": {
"hourly": 1,
"daily": 1,
"weekly": 1,
"monthly": 1
},
"linkedTo": {
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"listId": "customOrReservedListId"
},
"locale": "text",
"homePageView": {
"type": "badges",
"category": "text"
}
}
],
"nsfw": {
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"reason": "text"
},
"reported": {
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"reason": "text"
},
"views": {
"ANY_ADDITIONAL_PROPERTY": {
"ids": [
"text"
],
"type": "text",
"pagination": {
"bookmark": "text",
"hasMore": true
}
}
},
"claims": [
{
"_includesPrivateParams": true,
"claimId": "text",
"createdBy": "bb1...",
"managedBy": "bb1...",
"collectionId": "text",
"standaloneClaim": true,
"listId": "customOrReservedListId",
"trackerDetails": {
"collectionId": "text",
"approvalId": "text",
"challengeTrackerId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1..."
},
"balancesToSet": {
"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"
}
},
"plugins": [
{
"instanceId": "text",
"pluginId": 1,
"version": "text",
"publicParams": null,
"privateParams": null,
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png"
},
"publicState": null,
"privateState": null
}
],
"rewards": [
{
"rewardId": "text",
"instanceId": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png"
},
"automatic": true,
"gatedContent": {
"content": "text",
"url": "text",
"params": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"calculationMethod": {
"alwaysShow": true,
"minClaimSuccesses": 1
}
}
],
"estimatedCost": "text",
"showInSearchResults": true,
"categories": [
"text"
],
"estimatedTime": "text",
"manualDistribution": true,
"approach": "text",
"seedCode": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"assignMethod": "text",
"lastUpdated": 1,
"version": 1,
"satisfyMethod": {
"type": "AND",
"conditions": "[Circular Reference]",
"options": {
"minNumSatisfied": 1
}
},
"cachePolicy": {
"ttl": 1,
"alwaysPermanent": true,
"permanentAfter": "1713301889"
},
"_templateInfo": {
"supportedApproaches": [
"text"
],
"pluginId": "text",
"completedTemplateStep": true
}
}
],
"stats": {
"_docId": "text",
"_id": "text",
"overallVolume": [
{
"amount": 1,
"denom": "text"
}
],
"dailyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"weeklyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"monthlyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"yearlyVolume": [
{
"amount": 1,
"denom": "text"
}
],
"lastUpdatedAt": "1713301889",
"collectionId": "text",
"floorPrices": [
{
"amount": 1,
"denom": "text"
}
],
"uniqueOwners": [
{
"amount": 1,
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"ownershipTimes": [
{
"start": "1713301889",
"end": "2000000000"
}
]
}
],
"floorPriceHistory": [
{
"floorPrice": {
"amount": 1,
"denom": "text"
},
"updatedAt": "1713301889"
}
],
"payoutRewards": [
{
"amount": 1,
"denom": "text"
}
]
},
"badgeFloorPrices": [
{
"_docId": "text",
"_id": "text",
"collectionId": "text",
"badgeId": 1,
"floorPrices": [
{
"amount": 1,
"denom": "text"
}
],
"floorPriceHistory": [
{
"floorPrice": {
"amount": 1,
"denom": "text"
},
"updatedAt": "1713301889"
}
]
}
]
}
]
}Retrieves the balance of a specific token for a specific address at the current time.
For more advanced queries returning the whole balance document, please use the POST /collection/{collectionId}/balance/{address} endpoint.
const res = await BitBadgesApi.getBalanceByAddressSpecificToken(collectionId, address, badgeId);
console.log(res);SDK Links:
Alternative Flow: Note that you can also set up a claim that checks token ownership and check the success per user of that claim as well
Authorizations
Path parameters
collectionIdintegerRequired
The ID of the collection.
addressstringRequired
The address for which the balance is to be retrieved. Can be "Total" for the circulating supply.
badgeIdintegerRequired
The ID for which the balance is to be retrieved.
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
/collection/{collectionId}/balance/{address}/{badgeId}GET /api/v0/collection/{collectionId}/balance/{address}/{badgeId} HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Accept: */*
{
"balance": 1
}Retrieves the balances of a specific address for a collection.
const res = await BitBadgesApi.getBalanceByAddress(collectionId, address, { ...options });
console.log(res);SDK Links:
Scopes:
readPrivateClaimData- Required if fetching private claim data (user-level approvals)
Alternative Flow: Note that you can also set up a claim that checks token ownership and check the success per user of that claim as well
Authorizations
Path parameters
collectionIdintegerRequired
The ID of the collection.
addressstringRequired
The address for which the balance is to be retrieved. Can be "Total" for the circulating supply.
Query parameters
fetchPrivateParamsbooleanOptional
If true, we will fetch private parameters for any claims / approvals. Must be creator.
This is only applicable to incoming / outgoing approvals with claims.
forcefulbooleanOptional
If true, we will forcefully fetch the balance even if it is already cached. Only applicable to non-indexed / on-demand collections.
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
/collection/{collectionId}/balance/{address}GET /api/v0/collection/{collectionId}/balance/{address} HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"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"
}
]
}Retrieves the owners in a paginated format for a specific token in a collection. Returns a list of addresses and their corresponding balances for the specified token ID.
const res = await BitBadgesApi.getOwners(
collectionId,
badgeId,
{
bookmark: '...'
}
);SDK Links:
Authorizations
Path parameters
collectionIdintegerRequired
The numeric collection ID.
badgeIdintegerRequired
The numeric token ID to retrieve owners for.
Query parameters
bookmarkstringOptional
The pagination bookmark for where to start the request. Bookmarks are obtained via the previous response. "" for first request.
sortBystring · enumOptionalPossible values:
Sort by amount descending.
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
/collection/{collectionId}/{badgeId}/ownersGET /api/v0/collection/{collectionId}/{badgeId}/owners HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"owners": [
{
"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"
}
]
}
],
"pagination": {
"bookmark": "text",
"hasMore": true
}
}Retrieves the activity in a paginated format for a specific token in a collection.
const res = await BitBadgesApi.getTokenActivity(
collectionId,
badgeId,
{
bookmark: '...'
}
);SDK Links:
Authorizations
Path parameters
collectionIdintegerRequired
The ID of the collection.
badgeIdintegerRequired
The ID for which activity is to be retrieved.
Query parameters
bookmarkstringOptional
An optional bookmark for pagination. Bookmarks are obtained via the previous response. "" for first request.
bitbadgesAddressstringOptionalExample:
Specific address to filter by. If not present, all activity will be returned.
bb1...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
/collection/{collectionId}/{badgeId}/activityGET /api/v0/collection/{collectionId}/{badgeId}/activity HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"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"
}
],
"pagination": {
"bookmark": "text",
"hasMore": true
}
}Gets the refresh status for a collection. Used to track if any errors occur during a refresh, or if it is in the queue or not.
const res = await BitBadgesApi.getRefreshStatus(...);SDK Links:
Authorizations
Path parameters
collectionIdstringRequired
The collection ID
Responses
200
Success response
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/collection/{collectionId}/refreshStatusGET /api/v0/collection/{collectionId}/refreshStatus HTTP/1.1
Host: api.bitbadges.io
x-api-key: YOUR_API_KEY
Authorization: cookie YOUR_SECRET_TOKEN
Accept: */*
{
"inQueue": true,
"errorDocs": [
{
"_docId": "text",
"_id": "text",
"uri": "https://example.com",
"collectionId": "text",
"loadBalanceId": 1,
"refreshRequestTime": "1713301889",
"numRetries": 1,
"lastFetchedAt": "1713301889",
"error": "text",
"deletedAt": "1713301889",
"nextFetchTime": "1713301889",
"pending": true,
"emailMessage": "text",
"recipientAddress": "text",
"activityDocId": "text",
"notificationType": "text",
"initiatedBy": "bb1...",
"actionConfig": null,
"claimInfo": {
"session": null,
"body": null,
"claimId": "text",
"bitbadgesAddress": "bb1...",
"ip": "text",
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"faucetInfo": {
"txHash": "CE22D7...",
"amount": 1,
"recipient": "bb1...",
"denom": "text"
}
}
],
"refreshDoc": {
"_docId": "text",
"_id": "text",
"collectionId": "text",
"refreshRequestTime": "1713301889"
}
}Gets owners for a specific collection.
await BitBadgesApi.getCollectionOwners("123");SDK Links:
Authorizations
Path parameters
collectionIdstringRequired
Collection ID
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
/collection/{collectionId}/ownersGET /api/v0/collection/{collectionId}/owners HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"owners": [
{
"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"
}
]
}
],
"pagination": {
"bookmark": "text",
"hasMore": true
}
}Gets transfer activity for a specific collection.
await BitBadgesApi.getCollectionTransferActivity("123", { ... });SDK Links:
Authorizations
Path parameters
collectionIdstringRequired
Collection ID
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
addressstringOptional
Optional address to filter activity by
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
/collection/{collectionId}/activityGET /api/v0/collection/{collectionId}/activity HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"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"
}
],
"pagination": {
"bookmark": "text",
"hasMore": true
}
}Gets challenge trackers for a specific collection.
await BitBadgesApi.getCollectionChallengeTrackers("123", { ... });SDK Links:
Authorizations
Path parameters
collectionIdstringRequired
Collection ID
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
/collection/{collectionId}/challengeTrackersGET /api/v0/collection/{collectionId}/challengeTrackers HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"challengeTrackers": [
{
"_docId": "text",
"_id": "text",
"collectionId": "text",
"challengeTrackerId": "text",
"approvalId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1...",
"usedLeafIndices": [
{
"leafIndex": 1,
"usedBy": "bb1..."
}
]
}
],
"pagination": {
"bookmark": "text",
"hasMore": true
}
}Gets amount trackers for a specific collection.
await BitBadgesApi.getCollectionAmountTrackers("123", { ... });SDK Links:
Authorizations
Path parameters
collectionIdstringRequired
Collection ID
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
/collection/{collectionId}/amountTrackersGET /api/v0/collection/{collectionId}/amountTrackers HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"amountTrackers": [
{
"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"
}
],
"pagination": {
"bookmark": "text",
"hasMore": true
}
}Gets an amount tracker by ID for a collection.
await BitBadgesApi.getCollectionAmountTrackerById({ ... });SDK Links:
Authorizations
Query parameters
collectionIdstringRequired
The collection ID for the approval.
approvalIdstringRequired
The approval ID
amountTrackerIdstringRequired
The amount tracker ID of the approval.
approvalLevelstringRequiredExample:
The approval level of the approval "collection", "incoming", or "outgoing".
collectionapproverAddressstringRequiredExample:
The address of the approval to check.
bb1...trackerTypestringRequired
The type of tracker to check "overall", "to", "from", or "initiatedBy".
approvedAddressstringRequiredExample:
The address to check for the approval.
bb1...Responses
200
Success
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/api/v0/collection/amountTrackerGET /api/v0/api/v0/collection/amountTracker?collectionId=text&approvalId=text&amountTrackerId=text&approvalLevel=collection&approverAddress=bb1...&trackerType=text&approvedAddress=bb1... HTTP/1.1
Host: api.bitbadges.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"amountTracker": {
"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"
}
}Gets a challenge tracker by ID for a collection.
await BitBadgesApi.getCollectionChallengeTrackerById({ ... });SDK Links:
Authorizations
Query parameters
collectionIdstringRequired
The collection ID
approvalIdstringRequired
The approval ID
challengeTrackerIdstringRequired
The challenge ID
approvalLevelstring · enumRequiredExample:
The challenge level (i.e. "collection", "incoming", "outgoing")
collectionPossible values: approverAddressstringRequiredExample:
The approver address (leave blank if approvalLevel = "collection")
bb1...Responses
200
Success
application/json
400
Bad Request - Invalid configuration or request
application/json
500
Internal Server Error
application/json
get
/api/v0/collection/challengeTrackerGET /api/v0/api/v0/collection/challengeTracker?collectionId=text&approvalId=text&challengeTrackerId=text&approvalLevel=collection&approverAddress=bb1... HTTP/1.1
Host: api.bitbadges.io
x-api-key: YOUR_API_KEY
Accept: */*
{
"challengeTracker": {
"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"
}
}Gets listings for a specific collection.
await BitBadgesApi.getCollectionListings("123", { ... });SDK Links:
Authorizations
Path parameters
collectionIdstringRequired
Collection ID
Query parameters
bookmarkstringOptional
oldestFirstbooleanOptional
badgeIdany ofOptional
Optional token ID to filter listings by
numberOptional
stringOptional
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
/collection/{collectionId}/listingsGET /api/v0/collection/{collectionId}/listings HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"listings": [
{
"_docId": "text",
"_id": "text",
"listingId": "text",
"type": "text",
"createdBy": "bb1...",
"managedBy": "bb1...",
"directLink": "text",
"createdAt": "1713301889",
"lastUpdated": "1713301889",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"inheritMetadataFrom": {
"claimId": "text",
"applicationId": "text",
"collectionId": "text",
"listId": "customOrReservedListId",
"mapId": "text",
"badgeId": "text"
},
"content": [
{
"type": "text",
"label": "text",
"content": "text"
}
],
"links": [
{
"url": "text",
"claimId": "text",
"applicationId": "text",
"collectionId": "text",
"listId": "customOrReservedListId",
"mapId": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
}
}
],
"displayTimes": {
"start": 1,
"end": 1
},
"visibility": "public",
"categories": [
"text"
],
"approvalStatus": {
"isApproved": true,
"isFeatured": true,
"featuredPriority": 1,
"rejected": true,
"reason": "text",
"updatedBy": "bb1..."
},
"viewCount": 1,
"estimatedCost": {
"amount": 1,
"denom": "text"
},
"estimatedTime": "text",
"viewsByPeriod": {
"hourly": 1,
"daily": 1,
"weekly": 1,
"monthly": 1
},
"linkedTo": {
"collectionId": "text",
"badgeIds": [
{
"start": "1",
"end": "10"
}
],
"listId": "customOrReservedListId"
},
"locale": "text",
"homePageView": {
"type": "badges",
"category": "text"
}
}
],
"pagination": {
"bookmark": "text",
"hasMore": true
}
}Gets claims for a specific collection.
await BitBadgesApi.getCollectionClaims("123", { ... });SDK Links:
Scopes:
readPrivateClaimData- Required if fetching private claim data (also must be manager of collection)
Note: For fetching more advanced information like private claim data, you can do so with the get claim routes. Use the IDs from these responses.
Authorizations
Path parameters
collectionIdstringRequired
Collection ID
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
/collection/{collectionId}/claimsGET /api/v0/collection/{collectionId}/claims HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Accept: */*
{
"pagination": {
"bookmark": "text",
"hasMore": true
},
"claims": [
{
"_includesPrivateParams": true,
"claimId": "text",
"createdBy": "bb1...",
"managedBy": "bb1...",
"collectionId": "text",
"standaloneClaim": true,
"listId": "customOrReservedListId",
"trackerDetails": {
"collectionId": "text",
"approvalId": "text",
"challengeTrackerId": "text",
"approvalLevel": "collection",
"approverAddress": "bb1..."
},
"balancesToSet": {
"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"
}
},
"plugins": [
{
"instanceId": "text",
"pluginId": 1,
"version": "text",
"publicParams": null,
"privateParams": null,
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png"
},
"publicState": null,
"privateState": null
}
],
"rewards": [
{
"rewardId": "text",
"instanceId": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png"
},
"automatic": true,
"gatedContent": {
"content": "text",
"url": "text",
"params": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
},
"calculationMethod": {
"alwaysShow": true,
"minClaimSuccesses": 1
}
}
],
"estimatedCost": "text",
"showInSearchResults": true,
"categories": [
"text"
],
"estimatedTime": "text",
"manualDistribution": true,
"approach": "text",
"seedCode": "text",
"metadata": {
"name": "Name",
"description": "Brief description.",
"image": "https://example.com/image.png",
"bannerImage": "https://example.com",
"category": "text",
"externalUrl": "text",
"tags": [
"text"
],
"socials": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"offChainTransferabilityInfo": {
"host": "text",
"assignMethod": "text"
},
"attributes": [
{
"type": "text",
"name": "Name",
"value": "text"
}
],
"additionalInfo": [
{
"name": "Name",
"image": "https://example.com/image.png",
"description": "Brief description.",
"url": "text"
}
],
"fetchedAtBlock": 1,
"fetchedAt": "1713301889",
"_isUpdating": true
},
"assignMethod": "text",
"lastUpdated": 1,
"version": 1,
"satisfyMethod": {
"type": "AND",
"conditions": [
"text"
],
"options": {
"minNumSatisfied": 1
}
},
"cachePolicy": {
"ttl": 1,
"alwaysPermanent": true,
"permanentAfter": "1713301889"
},
"_templateInfo": {
"supportedApproaches": [
"text"
],
"pluginId": "text",
"completedTemplateStep": true
}
}
]
}Last updated