# Claims for Agents

Claims are BitBadges' flexible criteria engine. For agents, claims enable gated minting and transfers where off-chain criteria (codes, passwords, ownership checks, custom logic) control on-chain token operations. The core flow is: **create claim -> complete claim -> get merkle code -> use merkle code in MsgTransferTokens**.

## Two Claim Flows

**Standalone claims (off-chain only):** Criteria check -> reward. The reward is off-chain: points, address list spots, gated content access, etc. No blockchain transaction needed.

**On-chain gated claims:** Criteria check -> reserved merkle code -> merkle proof -> on-chain transfer/mint via `MsgTransferTokens`. This is the flow agents typically need.

## Creating a Claim Programmatically

Use the BitBadges API SDK to create claims. The example below creates a code-gated claim. To link it to an on-chain collection for gated minting, associate it with a collection approval via the BitBadges UI or API — the `collectionId` and `trackerDetails` are applied automatically.

```typescript
import crypto from 'crypto';
import { BitBadgesAPI } from 'bitbadges';

const api = new BitBadgesAPI({ apiUrl: 'https://api.bitbadges.io' });

// Generate codes
const seedCode = crypto.randomBytes(32).toString('hex');
const numCodes = 50;
const codes = [];
for (let i = 0; i < numCodes; i++) {
  codes.push(
    crypto.createHash('sha256').update(`${seedCode}-${i}`).digest('hex') + `-${i}`
  );
}

await api.createClaim({
  claims: [
    {
      plugins: [
        {
          pluginId: 'numUses',
          instanceId: 'num-uses',
          version: '0',
          publicParams: { maxUses: numCodes },
          privateParams: {}
        },
        {
          pluginId: 'codes',
          instanceId: 'codes-gate',
          version: '0',
          publicParams: { numCodes },
          privateParams: { codes, seedCode }
        }
      ],
      state: {},
      action: { seedCode },
      metadata: {
        name: 'My Agent Claim',
        description: 'Codes distributed by my bot'
      }
    }
  ]
});
```

If you are using the BitBadges Builder tools or the AI builder, use the `build_claim` tool instead of constructing the payload manually (see Builder Tool Workflow below). The AI builder auto-generates `seedCode` and codes server-side for the `codes` plugin — you only need to specify `numCodes` in `publicParams`.

## Completing a Claim

Claim completion is asynchronous. You submit the attempt, then poll for the result.

```typescript
// Submit the claim attempt
const res = await api.completeClaim(claimId, userAddress, {
  _expectedVersion: 0,
  'codes-gate': { code: codes[0] } // Plugin inputs keyed by instanceId
});

// Poll for result (~2-5 seconds)
let status;
do {
  await new Promise((r) => setTimeout(r, 2000));
  status = await api.getClaimAttemptStatus(res.claimAttemptId);
} while (!status.success && !status.error);

if (status.success) {
  console.log('Claim completed! Code:', status.code);
}
```

## The Merkle Proof Flow (On-Chain Claims)

This is the key flow agents need. After completing a claim for an on-chain collection, you must retrieve your reserved merkle code, build a proof, and submit it in a `MsgTransferTokens`.

### Step 1: Get reserved codes and leaf signatures

```typescript
const reserved = await api.getReservedClaimCodes(claimId, userAddress);
// reserved.reservedCodes = ['abc123...']
// reserved.leafSignatures = ['0x...']
```

### Step 2: Get the merkle proof path

```typescript
const proofInfo = await api.getMerkleProofInfo(
  collectionId,
  challengeTrackerId,
  reserved.reservedCodes[0]
);
// proofInfo.aunts = [{ aunt: 'hash', onRight: true }, ...]
```

### Step 3: Build and submit the transfer

```typescript
const result = await client.signAndBroadcast([
  MsgTransferTokens.create({
    creator: client.address,
    collectionId: '123',
    transfers: [
      {
        from: 'Mint',
        toAddresses: [client.address],
        balances: [
          {
            tokenIds: [{ start: '1', end: '1' }],
            amount: '1',
            ownershipTimes: [{ start: '1', end: '18446744073709551615' }]
          }
        ],
        merkleProofs: [
          {
            leaf: reserved.reservedCodes[0],
            leafSignature: reserved.leafSignatures[0],
            aunts: proofInfo.aunts
          }
        ],
        prioritizedApprovals: [
          {
            approvalId: 'mint-approval',
            approvalLevel: 'collection',
            approverAddress: '',
            version: '0'
          }
        ],
        onlyCheckPrioritizedCollectionApprovals: true,
        onlyCheckPrioritizedIncomingApprovals: false,
        onlyCheckPrioritizedOutgoingApprovals: false,
        memo: ''
      }
    ]
  })
]);
```

The `prioritizedApprovals` array tells the chain which approval to check. The `approvalId` must match the approval on the collection that references the claim's merkle challenge. Always specify `prioritizedApprovals` even if empty.

## Common Patterns for Agents

* **Bot distributes codes**: Create a code-gated claim, distribute codes to users via your app or bot, users complete the claim on BitBadges or you complete on their behalf.
* **Backend auto-completion**: Create a password-gated claim where only your backend knows the password. Complete claims on behalf of users when they meet your custom criteria.
* **Ownership-gated minting**: Use the `must-own-badges` plugin to gate minting based on existing token ownership. Users who hold token X can mint token Y.
* **Time-windowed drops**: Add `transferTimes` constraints to limit when claims can be completed.

## Builder Tool Workflow

If you are using the BitBadges Builder tools, the `build_claim` tool handles payload construction:

```
build_claim({
  claimType: "code-gated",
  name: "My Drop",
  maxUses: 100,
  action: { seedCode: "auto" }
})
```

The tool returns a claim payload ready for submission to the API. For the `codes` plugin, set `publicParams.numCodes` as a JS number (not a string) and leave `privateParams` empty — the server generates codes automatically. Use `search_plugins` to see all available claim plugins and their parameters.

From there, the agent follows the same complete -> get codes -> submit proof flow described above.

## Tips

* Always call `simulateClaim` before `completeClaim` in production to catch errors without consuming a use.
* Match `numUses` to the merkle tree leaf count for on-chain claims. A mismatch means some codes won't have valid proofs.
* Use `_expectedVersion` in `completeClaim` to prevent race conditions when multiple agents or users compete for the same claim.
* Poll `getClaimAttemptStatus` after submitting. Claims process asynchronously and typically resolve in 2-5 seconds.


---

# 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/ai-agents/claims-for-agents.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.