BitBadges API

Name: BitBadges 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.

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.

Step 1: Jentic One Host machine

# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh

Step 2: Agent machine

# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register       # connects your agent to your Jentic One instance

Jentic 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}

GET STARTED

Start building with BitBadges API

Explore with Jentic

View OpenAPI Document

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

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

BitBadges API

Connect the BitBadges API to your agent

Capabilities

Start building with BitBadges API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs