# 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:** ```typescript { code: string } ``` **Public Params:** ```typescript { numCodes: number; // Total number of codes hideCurrentState?: boolean; // Hide usage state from users } ``` **Private Params:** ```typescript { codes: string[]; // The actual codes seedCode: string; // Seed used to generate codes } ``` **Public State:** ```typescript { usedCodeRanges?: UintRange[]; // Ranges of used code indices } ``` *** ### `password` — Password Gate Gate claims behind a shared secret. **User Input:** ```typescript { password: string } ``` **Private Params:** ```typescript { 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:** ```typescript { maxUses: number; // Maximum total claims allowed hideCurrentState?: boolean; // Hide current count from users displayAsUnlimited?: boolean; // Display as "unlimited" in UI } ``` **Public State:** ```typescript { 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:** ```typescript { 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:** ```typescript { 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:** ```typescript { 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:** ```typescript { 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: ```typescript 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: ```typescript // 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: ```typescript 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: ```typescript 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 }; } ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.bitbadges.io/for-developers/claims/built-in-plugins.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.