BitBadges API
Agent-ready OpenAPI document · curated by JenticIdentity AuthIdentity VerificationapiKey6 EndpointsREST
Know of an official OpenAPI document? Contribute it →
For 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.
Use for: Generate a Sign-In with Web3 challenge for an Ethereum address, Verify a signature against a previously issued challenge, Check whether wallet 0xabc holds badge 42 in collection 7, List the badges in BitBadges collection 7
Not supported: 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.
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.
Install Jentic One Beta
Connect the BitBadges API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the BitBadges API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbitbadges.io%2Fbitbadges" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fbitbadges.io%2Fbitbadges" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with BitBadges API.
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
Patterns agents use BitBadges API for, with concrete tasks.
★ 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.
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.
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.
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.
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
6 endpoints — jentic publishes the only available openapi specification for bitbadges api, keeping it validated and agent-ready.
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
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
Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using BitBadges API through Jentic.
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.
GET STARTED