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.

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.

{
  "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