Built-In Plugins

This page documents the schemas for all core plugins and pre-built plugin-based plugins.

Core Plugins

Core plugins are built into BitBadges and handled in-memory. They require no external HTTP calls.

codes — Claim Codes

One-time use codes that users must present to claim.

User Input:

{ code: string }

Public Params:

{
  numCodes: number;           // Total number of codes
  hideCurrentState?: boolean; // Hide usage state from users
}

Private Params:

{
  codes: string[];   // The actual codes
  seedCode: string;  // Seed used to generate codes
}

Public State:

{
  usedCodeRanges?: UintRange[];  // Ranges of used code indices
}

---

password — Password Gate

Gate claims behind a shared secret.

User Input:

{ password: string }

Private Params:

{
  password: string;  // The password to check against
}

No public params or state.

---

numUses — Max Claims Limit

Limit the total number of successful claims. This plugin is always required and cannot be made optional via success logic.

Public Params:

{
  maxUses: number;              // Maximum total claims allowed
  hideCurrentState?: boolean;   // Hide current count from users
  displayAsUnlimited?: boolean; // Display as "unlimited" in UI
}

Public State:

{
  numUses?: number;                          // Current claim count
  usedClaimNumbers?: UintRange[];            // Which claim numbers are taken
  claimedUsers?: {
    [bitbadgesAddress: string]: number[];    // Claim numbers per address
  };
}

No user input.

---

transferTimes — Time Windows

Restrict when claims can be completed.

Public Params:

{
  transferTimes: UintRange[];  // Array of allowed time ranges (UNIX ms)
}

No user input, state, or private params.

---

initiatedBy — Sign-In Requirement

Requires the user to be signed in to BitBadges. This verifies the claiming address is authenticated.

No configurable params — configuration is handled in the claim builder UI.

---

whitelist — Address List Gate

Gate claims to a specific set of addresses. Supports both static address lists and dynamic stores.

Public Params:

{
  listId?: string;              // Reference to an existing address list
  list?: AddressList;           // Inline address list
  maxUsesPerAddress?: number;   // Max claims per address
  hasPrivateList?: boolean;     // True if the list is hidden from public
}

Private Params:

{
  useDynamicStore?: boolean;  // Use a dynamic store instead of static list
  dynamicDataId?: string;     // Dynamic store ID
  dataSecret?: string;        // Dynamic store secret
  listId?: string;            // Address list ID (private variant)
  list?: AddressList;         // Inline list (private variant)
}

Private State:

{
  addresses: { [address: string]: number };  // Claims per address
}

---

halt — Pause Claims

Temporarily halt all claim attempts. No params — just add/remove from the plugin list.

---

anonymous — Anonymous Claiming

Allow claims without requiring an address. No params.

---

Pre-Built Custom Plugins

These are pre-built plugins available by their plugin ID. They function as custom plugins (HTTP-based) but are maintained by BitBadges.

To look up their full schema (user inputs, public/private params), use the API:

const plugin = await BitBadgesApi.getPlugin('must-own-badges');
// plugin.versions[0].userInputsSchema
// plugin.versions[0].publicParamsSchema
// plugin.versions[0].privateParamsSchema

Plugin ID	Description
must-own-badges	Require ownership of specific badges/tokens. Configure which collection + token IDs.
min-badge	Require a minimum token/badge balance.
url-clicker	Require the user to visit a specific URL.
custom-instructions	Display custom instructions to the user (informational only).
satisfies-claim	Require the user to have completed another claim first.
username-set	Require the user to have set a BitBadges username.

Looking Up Plugin Schemas

You can look up any plugin's configuration schema via the API:

// Get a single plugin by ID
const res = await BitBadgesApi.getPlugin('must-own-badges');
const latestVersion = res.versions[res.versions.length - 1];

console.log(latestVersion.userInputsSchema);    // What users must provide
console.log(latestVersion.publicParamsSchema);   // Creator-configured public params
console.log(latestVersion.privateParamsSchema);  // Creator-configured private params
console.log(latestVersion.stateFunctionPreset);  // State management type
console.log(latestVersion.verificationCall);     // HTTP endpoint config

// Fetch multiple plugins at once
const res = await BitBadgesApi.getPlugins({
  pluginIds: ['must-own-badges', 'min-badge', 'url-clicker'],
  returnSensitiveData: false  // true = include pluginSecret (owner only)
});

// Search published plugins by name
const res = await BitBadgesApi.searchPlugins({
  searchValue: 'badge',
  bookmark: undefined,  // For pagination
  locale: 'en'
});

Plugin Version Config

Each plugin version contains the full configuration:

interface PluginVersionConfig {
  version: number;
  finalized: boolean;              // Only finalized versions are usable
  stateFunctionPreset: 'Stateless' | 'ClaimToken' | 'ClaimNumbers' | 'CustomResponseHandler';
  duplicatesAllowed: boolean;      // Can a claim have multiple instances?
  requiresSessions: boolean;       // Needs authenticated session?
  requiresUserInputs: boolean;     // Needs user interaction?
  reuseForNonIndexed: boolean;     // Compatible with on-demand claims?
  receiveStatusWebhook: boolean;   // Receive status updates?
  skipProcessingWebhook?: boolean; // Auto-pass without calling endpoint?
  ignoreSimulations?: boolean;     // Skip during dry-runs?
  requireSignIn?: boolean;         // Require BitBadges sign-in?

  // Schemas (JsonBodyInputSchema arrays)
  userInputsSchema: JsonBodyInputSchema[];
  publicParamsSchema: JsonBodyInputSchema[];
  privateParamsSchema: JsonBodyInputSchema[];

  // HTTP endpoint configuration
  verificationCall?: {
    uri: string;
    hardcodedInputs: JsonBodyInputWithValue[];
    passAddress?: boolean;
  };

  // UI customization
  customDetailsDisplay?: string;   // Template: "Requires {{minBalance}} tokens"
}

Schema Field Types

Each schema field (JsonBodyInputSchema) describes one input:

interface JsonBodyInputSchema {
  key: string;                 // Field name in payload
  label: string;               // Display label
  type: string;                // 'string' | 'number' | 'boolean' | 'date' | 'url'
  required?: boolean;
  defaultValue?: string | number | boolean;
  helper?: string;             // Help text
  options?: { label: string; value: string | number | boolean }[];  // Dropdown
  arrayField?: boolean;        // Is this an array?
  headerField?: boolean;       // Pass as HTTP header instead of body?
  hideFromDetailsDisplay?: boolean;  // Hide from public view (public params only)
  hyperlink?: { url: string; showAsGenericView?: boolean };
}