canonical: https://jentic.com/apis/bitbadges.io/bitbadges

# BitBadges API

Jentic publishes the only available OpenAPI specification for BitBadges API, keeping it validated and agent-ready. BitBadges is a cross-chain platform for issuing, holding, and verifying digital badges and credentials. The API exposes a Sign-In with Web3 challenge-and-verify flow, collection-level badge lookups, and per-user balance checks so a server can confirm whether an address holds a particular badge. Six endpoints cover authentication, collection metadata, and address-level badge balances.

## For AI agents

Issue Sign-In with Web3 challenges, verify wallet signatures, and check whether an address holds a particular BitBadge. Six endpoints, X-API-Key header authentication.

## Scope

Does not mint badges on-chain, manage wallet private keys, or run a node - use for credential issuance challenges, signature verification, and balance lookups only.

## Capabilities

- Generate a Sign-In with Web3 challenge for a wallet address via `/api/v0/auth/getChallenge`
- Verify a signed challenge and confirm wallet ownership via `/api/v0/auth/verify`
- Look up a badge collection's metadata via `/api/v0/collections/{collectionId}`
- Check whether a specific address holds a badge from a collection via `/api/v0/users/{address}/balance/{collectionId}`
- Read a user's public BitBadges profile via `/api/v0/users/{address}`
- Gate access to a feature on holding a specific badge balance

## Use cases

### Wallet-based sign-in for a web app

Apps that want a wallet-based login replace email-and-password with a challenge-and-signature flow. 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 wallet ownership and the server issues its own session. Integration takes a day end-to-end because the two endpoints handle the cryptographic heavy lifting.

Example prompt: Call `/api/v0/auth/getChallenge` for the user's address, prompt the wallet to sign, then POST the signature to `/api/v0/auth/verify` and create a session on success

### Badge-gated feature access

Communities gate Discord roles, course modules, or product features on holding a specific badge. The server calls `/api/v0/users/{address}/balance/{collectionId}` after authenticating the wallet to read the holder's balance for the gating collection. A non-zero balance unlocks the feature. The endpoint returns balances directly so the server avoids parsing on-chain events itself.

Example prompt: Read the balance for collection 7 against the authenticated address and grant the 'verified holder' role when balance > 0

### Profile lookup for community directories

Community directories show every member's badge collection in one place. The server calls `/api/v0/users/{address}` to retrieve the profile and joins the response with `/api/v0/collections/{collectionId}` for each badge to render names and images. The two-call pattern is enough to render a holder card without the directory needing its own indexer.

Example prompt: Fetch `/api/v0/users/0xabc`, then for each badge in the response fetch `/api/v0/collections/{collectionId}` and assemble a holder card

### Agent integration via Jentic for credential verification

An AI agent that needs to confirm a user's credential before performing a privileged action calls Jentic with the intent 'verify wallet holds a specific credential'. Jentic returns the BitBadges balance operation with its input schema (address, collectionId). The X-API-Key never leaves your Jentic One instance, so the agent can confirm ownership without ever holding the secret.

Example prompt: Search Jentic for 'check whether wallet holds badge', load the balance schema, and execute with the user's address and the gating collectionId

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/v0/auth/getChallenge` | Mint a Sign-In with Web3 challenge for a wallet |
| POST | `/api/v0/auth/verify` | Verify a signed challenge and confirm wallet ownership |
| GET | `/api/v0/collections/{collectionId}` | Read metadata for a badge collection |
| GET | `/api/v0/users/{address}` | Return a user's public BitBadges profile |
| GET | `/api/v0/users/{address}/balance/{collectionId}` | Return an address's balance for a specific collection |

## Key resources

- **Authentication** — Generate Sign-In with Web3 challenges and verify signed responses
- **Collections** — List collections and read collection metadata
- **Users** — Read user profiles and per-collection badge balances

## Why Jentic

- **Setup:** Wiring the BitBadges API by hand means setting the X-API-Key header, targeting the api.bitbadges.io host, and handling the challenge-and-verify flow yourself. Through Jentic you install once, import BitBadges from the API Directory, store the key once, and your agent calls it.
- **Permission scoping:** BitBadges puts the collection id and address in the URL path (`/collections/{collectionId}`, `/users/{address}`), so a rule can pin your agent to one collection or address: it can read balances and details for that resource and nothing else. You choose the operations it may call, so the auth challenge and verify steps are not included unless you add them.
- **Credential handling:** Your BitBadges X-API-Key is stored once, encrypted, by your own Jentic One instance and injected into the header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'verify a wallet holds a badge' or 'look up a badge balance', and Jentic returns the matching BitBadges operation with its input and response schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Alchemy** — Multi-chain node and indexer with NFT and ownership endpoints that can substitute for badge lookups.
- **Covalent (GoldRush)** — Unified blockchain data API covering balances and token holdings across networks.
- **Blockchain.com API** — Public chain data for Bitcoin and major networks alongside off-chain credential checks.

## FAQ

### Why is there no official OpenAPI spec for BitBadges API?

BitBadges does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call BitBadges API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer.

### 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.