# API Reference

## Completing Claims

```typescript
// Both address formats work (Ethereum 0x or BitBadges bb-prefixed)
const res = await BitBadgesApi.completeClaim(claimId, address, body);
console.log(res.claimAttemptId);

// Wait ~2 seconds for processing, then check status
const status = await BitBadgesApi.getClaimAttemptStatus(res.claimAttemptId);
console.log(status); // { success: true }
```

### Request Body

```typescript
{
  _expectedVersion: '0',  // Required: claim.version (use -1 to unsafely skip check — not recommended)
  [instanceId]: {          // Per-plugin inputs, keyed by instance ID
    ...pluginInputs
  }
}
```

**Example:**

```typescript
await BitBadgesApi.completeClaim(claimId, 'bb1...', {
    _expectedVersion: '0',
    'password-instance': { password: 'secret123' },
    'codes-instance': { code: 'abc-def-ghi' },
});
```

### Notes

* `_expectedVersion` prevents the claim creator from changing criteria without you knowing. Obtain from `getClaim()`.
* If sign-in is required, you must have proper session authentication.
* If sign-in is disabled, gate the claim another way (e.g., password only your backend knows).
* The `completeClaim` route auto-simulates first. If simulation fails, it returns immediately without queuing.

## Simulating Claims

```typescript
const res = await BitBadgesApi.simulateClaim(claimId, address, body);
```

* Instant (not queued) — returns result immediately
* Same body format as `completeClaim`
* Use `_specificInstanceIds` to simulate only certain plugins:

```typescript
await BitBadgesApi.simulateClaim(claimId, address, {
  _expectedVersion: '0',
  _specificInstanceIds: ['plugin-a', 'plugin-b'],  // Only test these
  'plugin-a': { ... }
});
```

## Verifying Claim Attempts

### By Address

```typescript
// GET /api/v0/claims/success/{claimId}/{address}
const res = await BitBadgesApi.checkClaimSuccess(claimId, address);
if (res.successCount >= 1) {
    // User has successfully claimed
}
```

* `successCount` = number of completions (1 for on-demand, N for standard)
* Both `0x` and `bb1` address formats work

### By Attempt ID

```typescript
// GET /api/v0/claims/status/{claimAttemptId}
const res = await BitBadgesApi.getClaimAttemptStatus(claimAttemptId);
if (res.success) {
    // This specific attempt succeeded
}
```

Obtain `claimAttemptId` from the `completeClaim()` response or from a custom plugin.

### Polling Pattern

Claims process asynchronously. After calling `completeClaim()`, poll for the result:

```typescript
const res = await BitBadgesApi.completeClaim(claimId, address, body);

// Poll every 2-3 seconds until resolved
const pollStatus = async (
    attemptId: string,
    maxRetries = 10,
): Promise<boolean> => {
    for (let i = 0; i < maxRetries; i++) {
        await new Promise((r) => setTimeout(r, 2000));
        const status = await BitBadgesApi.getClaimAttemptStatus(attemptId);
        if (status.success !== undefined) return status.success;
    }
    throw new Error('Claim processing timed out');
};

const success = await pollStatus(res.claimAttemptId);
```

Typical processing time is 1-5 seconds. Claims for the same collection process sequentially; different collections process in parallel.

## Fetching Claims

```typescript
const claim = await BitBadgesApi.getClaim({
    claimId: 'your-claim-id',
    fetchPrivateParams: false, // true = include private params (owner only + auth)
    fetchAllClaimedUsers: true, // Include list of all claimed users
    privateStatesToFetch: ['instanceId'], // Fetch private state for specific plugins
});
```

## Looking Up Plugins

### Get a Single Plugin

```typescript
// GET /api/v0/plugins/{pluginId}
const plugin = await BitBadgesApi.getPlugin('must-own-badges');

// Inspect the latest version's schemas
const latest = plugin.versions[plugin.versions.length - 1];
console.log(latest.userInputsSchema); // What users provide
console.log(latest.publicParamsSchema); // Creator-configured public params
console.log(latest.privateParamsSchema); // Creator-configured private params
console.log(latest.verificationCall); // HTTP endpoint config
console.log(latest.stateFunctionPreset); // 'Stateless' | 'ClaimToken' | 'ClaimNumbers' | 'CustomResponseHandler'
```

### Fetch Multiple Plugins

```typescript
// POST /api/v0/plugins/fetch
const res = await BitBadgesApi.getPlugins({
    pluginIds: ['must-own-badges', 'min-badge', 'url-clicker'],
    returnSensitiveData: false, // true = include pluginSecret (owner only)
});
```

### Search Published Plugins

```typescript
// GET /api/v0/plugins/search
const res = await BitBadgesApi.searchPlugins({
    searchValue: 'badge', // Filter by name
    bookmark: undefined, // Pagination cursor
    locale: 'en',
});
```

### Get Plugin Errors

```typescript
const errors = await BitBadgesApi.getPluginErrors({
    pluginId: 'your-plugin-id',
    // ... pagination options
});
```

Useful for debugging failed plugin executions during development.

## Deleting Claims

```typescript
await BitBadgesApi.deleteClaims({ claimIds: ['claim-id-1', 'claim-id-2'] });
```

Deletion is a soft-delete — the claim is marked with `deletedAt` and excluded from queries. Existing claim attempt records are preserved for history.

## Searching Claims

```typescript
const res = await BitBadgesApi.searchClaims({
    searchValue: 'nft mint',
    bookmark: undefined, // Pagination cursor
});
```

Only claims with `showInSearchResults: true` appear in search results.


---

# 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/api-reference.md?ask=<question>
```

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.