What authentication does the BitBadges API use?

BitBadges uses an apiKey scheme. The key is passed in the X-API-Key request header on every call. Through Jentic the key is held encrypted in the vault and injected at call time, so the agent context never contains the raw secret.

Can I check whether a wallet holds a specific badge?

Yes. GET /api/v0/users/{address}/balance/{collectionId} returns the holder's balance for the named collection. A non-zero balance means the address holds at least one badge from that collection. Use it after authenticating the wallet so the holder cannot spoof a foreign address.

How does the BitBadges Sign-In with Web3 flow work?

The server calls /api/v0/auth/getChallenge to mint a one-time message, the user signs it in their wallet, and the server posts the signature to /api/v0/auth/verify. A successful verify confirms ownership of the address and the server issues its own session token.

How do I verify badge ownership through Jentic?

Run pip install jentic, search Jentic for 'check whether wallet holds badge', load the balance operation schema, and execute with the user's address and the gating collectionId. Jentic injects the X-API-Key automatically.

What are the rate limits for the BitBadges API?

BitBadges does not publish a numeric per-second rate limit in its specification. Treat balance and collection lookups as cacheable for short windows when building leaderboards or directories so a single page render does not fan out into hundreds of calls.

Can I limit what my agent is allowed to do with the BitBadges API?

Yes. Because you run Jentic One yourself, your own rules decide which BitBadges operations and credentials the agent may use. BitBadges puts the collection id and address in the URL path, such as /collections/{collectionId} and /users/{address}, so a rule can pin the agent to a single collection or address and let it read only that resource's balances and metadata. You also choose the operations it can call, so you can allow the balance and collection lookups while keeping the Sign-In with Web3 getChallenge and verify steps out of reach unless you add them.