# bb-402

<!-- generated by site/scripts/gen-skills.ts; do not hand-edit -->

# BB-402 Token-Gated Access

Instruction text for agents that use the BB-402 Token-Gated Access skill, loaded by `bb dev skills bb-402` and the MCP `get_skill_instructions` tool.

## Try it

Paste this into Claude Code, Codex, or Cursor with the BitBadges MCP server wired. The agent loads the skill, builds, verifies, and hands back a link to review and sign.

```text
Load the bb-402 skill and build me one: token-gated access protocol where ownership of specific badges grants API/resource access. Use the session tools, run validate, review, and simulate in parallel, fix anything critical, then call get_review_url and give me the link.
```

From a shell, `bb dev skills bb-402` prints the same instructions.

## Summary

Protocol for token-gated access to APIs/resources using HTTP 402 Payment Required.

- Flow: client requests resource -> server returns 402 + required badge criteria -> client proves ownership -> server validates via BitBadges API
- ownershipRequirements: use $and for "must have all", $or for "must have any"
- mustOwnAmounts: { start: 1, end: 1 } = must own at least 1
- mustOwnAmounts: { start: 0, end: 0 } = must not own (exclusion)
- Tiered access: different token IDs = different access levels
- Time-bounded access: combine ownershipTimes with subscription tokens
- Server-side verification: BitBadgesApi.verifyOwnership() or Blockin sign-in

## Instructions

## BB-402 Token-Gated Access Protocol

BB-402 is a protocol for token-gated access to APIs and digital resources. It uses HTTP 402 Payment Required responses to signal that badge ownership is needed.

### How It Works

1. Client requests a protected resource
2. Server responds with HTTP 402 + required badge criteria
3. Client proves badge ownership (signs a challenge or presents proof)
4. Server validates ownership via BitBadges API and grants access

### Design Patterns

#### Pattern 1: Simple Badge Gate
Require ownership of a specific badge to access a resource.

```json
{
  "ownershipRequirements": {
    "$and": [{
      "assets": [{
        "chain": "BitBadges",
        "collectionId": 123,
        "assetIds": [{ "start": 1, "end": 1 }],
        "mustOwnAmounts": { "start": 1, "end": 1 },
        "ownershipTimes": []
      }]
    }]
  }
}
```

#### Pattern 2: Tiered Access
Different badge IDs = different access levels.
- Token ID 1 = Basic access
- Token ID 2 = Premium access
- Token ID 3 = Admin access

#### Pattern 3: Time-Bounded Access
Use ownershipTimes to restrict access to users who own the badge during specific periods. Combine with subscription tokens for recurring access.

#### Pattern 4: Multi-Collection Gate
Require badges from multiple collections using $and/$or logic.

### Implementation Steps

1. **Create the gate badge collection**: Use NFT, fungible, or subscription patterns
2. **Configure ownership requirements**: Define what badges grant what access
3. **Server integration**: Use BitBadges API to verify ownership:
   - `BitBadgesApi.verifyOwnership()` for programmatic checks
   - Blockin sign-in for session-based authentication
4. **Client integration**: Handle 402 responses, present proof of ownership

### BB-402 Gotchas

- Badge ownership checks are point-in-time, consider caching strategies
- For subscription-based access, check ownershipTimes overlap with current time
- Use $and for "must have all", $or for "must have any"
- mustOwnAmounts: { start: 0, end: 0 } means must not own (exclusion)
- mustOwnAmounts: { start: 1, end: 1 } means must own at least 1