Address Lists

Endpoints for managing address lists

Get Address List

get
/addressList/{addressListId}

Gets an address list by specific ID.

await BitBadgesApi.getAddressList("addressList123", { ... });

SDK Links:

Note: The views and corresponding fields like listActivity, 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
addressListIdstringRequired

Address list ID

Responses
200

Success response

application/json
get
/addressList/{addressListId}
GET /api/v0/addressList/{addressListId} HTTP/1.1
Host: api.bitbadges.io
x-api-key: YOUR_API_KEY
Accept: */*

{
  "addressList": null
}

Creates Address Lists

post
/addressLists

Creates address lists stored by BitBadges centralized servers.

const res = await BitBadgesApi.createAddressLists(...);

SDK Links:

Scopes:

  • manageAddressLists - Required

Authorizations
Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Body
Responses
200

Success response

application/json
Responseobject
post
/addressLists
POST /api/v0/addressLists HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 3047

{
  "addressLists": [
    {
      "listId": "customOrReservedListId",
      "addresses": [
        "text"
      ],
      "whitelist": true,
      "uri": "https://example.com",
      "customData": "text",
      "updateAddresses": true,
      "claims": [
        {
          "claimId": "text",
          "collectionId": "text",
          "listId": "customOrReservedListId",
          "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"
            }
          },
          "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",
          "satisfyMethod": {
            "type": "AND",
            "conditions": "[Circular Reference]",
            "options": {
              "minNumSatisfied": 1
            }
          },
          "cachePolicy": {
            "ttl": 1,
            "alwaysPermanent": true,
            "permanentAfter": "1713301889"
          },
          "cid": "text",
          "plugins": [
            {
              "instanceId": "text",
              "pluginId": 1,
              "version": "text",
              "publicParams": null,
              "privateParams": null,
              "metadata": {
                "name": "Name",
                "description": "Brief description.",
                "image": "https://example.com/image.png"
              },
              "resetState": true,
              "newState": null,
              "onlyUpdateProvidedNewState": true
            }
          ]
        }
      ],
      "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"
          }
        ]
      }
    }
  ]
}
{}

Delete Address Lists

delete
/addressLists

Deletes address lists. Must be created off-chain.

const res = await BitBadgesApi.deleteAddressLists(...);

SDK Links:

Scopes:

  • manageAddressLists - Required

Authorizations
Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Body
listIdsstring[]Required

The list IDs to delete.

Responses
200

Success response

application/json
Responseobject
delete
/addressLists
DELETE /api/v0/addressLists HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "listIds": [
    "text"
  ]
}
{}

Update Address List Core Details

put
/addressLists/coreDetails

Updates the core details of an off-chain address list. This does not include address updates or claim updates.

const res = await BitBadgesApi.updateAddressListCoreDetails(...);

SDK Links:

Scopes:

  • manageAddressLists - Required

Authorizations
Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Body
listIdstringRequired

The ID of the address list.

Example: customOrReservedListId
whitelistbooleanRequired

Whether or not to include ONLY the addresses or include all EXCEPT the addresses.

uristringRequired

The URI where to fetch the address list metadata from.

Example: https://example.com
customDatastringRequired

Arbitrary custom data that can be stored. Leave blank for no custom data.

Responses
200

Success response

application/json
Responseobject
put
/addressLists/coreDetails
PUT /api/v0/addressLists/coreDetails HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 589

{
  "listId": "customOrReservedListId",
  "whitelist": true,
  "uri": "https://example.com",
  "customData": "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"
      }
    ]
  }
}
{}

Update Address List Addresses

put
/addressLists/addresses

Updates the addresses of an off-chain address list. This does not include claim updates or core details updates.

Note: This is a complete overwrite. If you have active claims, ensure no race conditions.

const res = await BitBadgesApi.updateAddressListAddresses(...);

SDK Links:

Scopes:

  • manageAddressLists - Required

Authorizations
Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Body
listIdstringRequired

The list ID to update.

Example: customOrReservedListId
addressesstring[]Required

The addresses to update. This is a full overwrite for ALL addresses.

If you have active claims, ensure this does not conflict via race conditions.

Responses
200

Success response

application/json
Responseobject
put
/addressLists/addresses
PUT /api/v0/addressLists/addresses HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Content-Type: application/json
Accept: */*
Content-Length: 56

{
  "listId": "customOrReservedListId",
  "addresses": [
    "text"
  ]
}
{}

Get Address Lists - Batch

post
/addressLists/fetch

Gets address lists. This uses an all-in-one approach with views and paginations to fetch details about the list all in one place. Note: Fetching views via this route is not supported. Use the other GET simpler routes. This may be deprecated soon.

const listsRes = await BitBadgesApi.getAddressLists([{
    //example
    listId: "...",
    viewsToFetch: [{
        viewType: 'listActivity',
        viewId: 'listActivity',
        bookmark: ''
    }]
}])

const list = listsRes[0];

Documentation References / Tutorials:

SDK Links:

Scopes:

  • readPrivateClaimData - Required if fetching private claim data

Note: This route has a lot of legacy features that may be deprecated soon. For views, p-lease use the other GET simpler routes.

Authorizations
Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Body
Responses
200

Success response

application/json
post
/addressLists/fetch
POST /api/v0/addressLists/fetch HTTP/1.1
Host: api.bitbadges.io
x-api-key: text
Authorization: cookie YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 157

{
  "listsToFetch": [
    {
      "listId": "customOrReservedListId",
      "viewsToFetch": [
        {
          "viewId": "viewKey",
          "viewType": "viewKey",
          "bookmark": "text"
        }
      ],
      "fetchPrivateParams": true
    }
  ]
}
{
  "addressLists": []
}

Get Address List Activity

get
/addressLists/{addressListId}/activity

Gets activity for a specific address list.

await BitBadgesApi.getAddressListActivity("list123", { ... });

SDK Links:

Authorizations
Path parameters
addressListIdstringRequired

Address list ID

Query parameters
bookmarkstringOptional
Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Responses
200

Success response

application/json
get
/addressLists/{addressListId}/activity
GET /api/v0/addressLists/{addressListId}/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,
      "listId": "customOrReservedListId",
      "initiatedBy": "bb1...",
      "addedToList": true,
      "addresses": [
        "bb1..."
      ],
      "txHash": "CE22D7..."
    }
  ],
  "pagination": {
    "bookmark": "text",
    "hasMore": true
  }
}

Get Address List Listings

get
/addressLists/{addressListId}/listings

Gets listings for a specific address list.

await BitBadgesApi.getAddressListListings("list123", { ... });

SDK Links:

Authorizations
Path parameters
addressListIdstringRequired

Address list ID

Query parameters
bookmarkstringOptional
Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Responses
200

Success response

application/json
get
/addressLists/{addressListId}/listings
GET /api/v0/addressLists/{addressListId}/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
  }
}

Get Address List Claims

get
/addressLists/{addressListId}/claims

Gets claims for a specific address list.

await BitBadgesApi.getAddressListClaims("list123", { ... });

SDK Links:

Scopes:

  • readPrivateClaimData - Required if fetching private claim data (also must be manager of address list)

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
addressListIdstringRequired

Address list ID

Header parameters
x-api-keystringRequired

BitBadges API Key for authentication

Responses
200

Success response

application/json
get
/addressLists/{addressListId}/claims
GET /api/v0/addressLists/{addressListId}/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
      }
    }
  ]
}
PreviousSign In with BitBadgesNextTransactions

Last updated