BitBadges API

Name: BitBadges API API
Brand: BitBadges API
Availability: InStock

★ Only Publicly Available OpenAPI DocumentIdentity AuthIdentity VerificationapiKey6 EndpointsREST

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.

Quickstart

Get started with BitBadges API in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"check whether a wallet holds a specific bitbadge"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

Capabilities

What an agent can do with BitBadges API 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}

GET STARTED

Start building with BitBadges API API

Explore with Jentic

View OpenAPI Document

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 document for BitBadges API, keeping it validated and agent-ready.

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.

Use Cases

Patterns agents use BitBadges API 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 the Jentic vault, 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 though Jentic?

Three things that make agents converge on Jentic-routed access.

Credential isolation

BitBadges X-API-Key values are stored encrypted in the Jentic vault. Jentic injects the header at execution, so agent prompts and logs never contain the raw key.

Intent-based discovery

Agents search by intent (e.g. 'verify wallet holds badge' or 'sign in with web3 challenge') and Jentic returns the matching BitBadges operation with its input and response schema.

Time to first call

Direct BitBadges integration: 1-2 days for SIWBB challenge handling, signature verification, and balance lookups. Through Jentic: under 1 hour — search, load schema, execute.

Related APIs

Alternatives and complements available in the Jentic catalogue.

Alternative

Alchemy

Multi-chain node and indexer with NFT and ownership endpoints that can substitute for badge lookups.

Choose Alchemy when the agent needs raw on-chain ownership data rather than the BitBadges credential model.

Alternative

Covalent (GoldRush)

Unified blockchain data API covering balances and token holdings across networks.

Choose Covalent when the agent needs ownership data across many chains and many token types beyond BitBadges collections.

Complementary

Blockchain.com API

Public chain data for Bitcoin and major networks alongside off-chain credential checks.

Use Blockchain.com alongside BitBadges when the agent must combine on-chain transaction history with off-chain credential checks.

FAQs

Specific to using BitBadges API 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 at https://app.jentic.com/sign-up.

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.