# AI Agents & Bots

This section is for developers building AI agents, bots, and automated systems that interact with the BitBadges blockchain. Whether you're building an autonomous minting agent, a gating bot, or an AI-powered claim system, you'll find everything you need here.

## Install

```bash
curl -fsSL https://install.bitbadges.io | sh
```

This installs the chain binary and SDK CLI. For CLI-based agent workflows (query, review, transact — no TypeScript needed), see [CLI for AI Agents](/for-developers/cli/for-ai-agents.md).

## 5-Minute Quickstart (TypeScript)

```bash
npm install bitbadges
```

```typescript
import { BitBadgesSigningClient, GenericEvmAdapter, MsgTransferTokens, NETWORK_CONFIGS } from 'bitbadges';

// 1. Create adapter from mnemonic (server-side)
const adapter = await GenericEvmAdapter.fromMnemonic(
  'your twelve word mnemonic phrase here ...',
  NETWORK_CONFIGS['testnet'].evmRpcUrl
);

// 2. Create signing client (testnet)
const client = new BitBadgesSigningClient({
  adapter,
  network: 'testnet'
});

// 3. Get testnet tokens
await fetch('https://api.bitbadges.io/testnet/api/v0/faucet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ address: client.address })
});

// 4. Broadcast your first transaction
const result = await client.signAndBroadcast([
  MsgTransferTokens.create({
    creator: client.address,
    collectionId: '1',
    transfers: [/* ... */]
  })
]);

console.log('TX Hash:', result.txHash);
```

## Metadata: No Hosting Required

The CLI builders and templates accept `--name`, `--image`, and `--description` (or `--name` + `--description` for approvals — no image) and serialize them into the on-chain `customData` field. The indexer, SDK, and frontend parse `customData` on read and surface the result as the resolved metadata, so an agent can ship a working collection without an IPFS pin or Pinata account. Pass `--uri <pre-hosted-uri>` instead if you would rather host the JSON yourself; URI takes priority when both are populated. See [Collection Configuration › Inline metadata via customData](/token-standard/learn/collection-setup-fields.md#inline-metadata-via-customdata) for the on-chain shape.

> **`--image` should be a URL, not bytes.** Inline `customData` lives on-chain — you pay gas per byte and blocks have a hard size cap. Pre-host images on IPFS (or any URL host) and pass the URL to `--image`. Inline customData is for the metadata wrapper (name, description, link to image), not the image itself. See [Cost considerations](/token-standard/learn/collection-setup-fields.md#cost-considerations-keep-images-off-chain).
>
> **Want zero hosting AND an image?** The SDK ships a deterministic SVG placeholder-art generator (`import { generatePlaceholderArt } from 'bitbadges'`) that produces 1-8 KB `data:image/svg+xml;base64,...` URIs you can drop into `--image`. Same seed always produces the same art. Trade-off: the SVG bytes still live on-chain — a 1-8 KB SVG costs an extra \~10-80k gas per write versus a hosted-URL image. Cheap convenience for placeholder-y looks; not the right call for image-heavy or high-frequency-update collections. See [Optional: deterministic SVG placeholder art](/token-standard/learn/collection-setup-fields.md#optional-deterministic-svg-placeholder-art-zero-hosting-image).

## Integration Paths

The chain binary + CLI install is the canonical entrypoint for everything below — install it first, then layer whichever harness-specific convenience you want on top.

| Path                                  | Best For                                                                         | Install                                                                                                                                          |
| ------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| **CLI & Chain Binary** *(start here)* | Terminal agents, shell scripts, any language                                     | `curl -fsSL https://install.bitbadges.io \| sh` — [guide](/for-developers/cli/for-ai-agents.md)                                                  |
| **BitBadges Builder Tools (MCP)**     | Cursor, Claude Desktop, other MCP clients                                        | `npm i -g bitbadges` — [guide](/for-developers/ai-agents/builder-tools.md)                                                                       |
| **Claude Code Plugin**                | Claude Code users — auto-wired MCP + 8 workflow skills (built on top of the CLI) | `/plugin marketplace add BitBadges/bitbadges-plugin` then `/plugin install bitbadges` — [guide](/for-developers/ai-agents/claude-code-plugin.md) |
| **SDK Signing Client**                | Full-featured TypeScript bots                                                    | `npm i bitbadges`                                                                                                                                |
| **Direct HTTP**                       | Lightweight scripts, any language                                                | REST calls to `api.bitbadges.io`                                                                                                                 |
| **Agent Spending Authorization**      | Set daily caps, time windows, and revocation                                     | [guide](/for-developers/ai-agents/agent-spending-authorization.md)                                                                               |

### Quick Setup

```bash
# Step 1 — install the chain binary + CLI (always)
curl -fsSL https://install.bitbadges.io | sh
bitbadges-cli config set apiKey YOUR_KEY

# Step 2 — optionally layer a harness convenience
# Claude Code:
#   /plugin marketplace add BitBadges/bitbadges-plugin
#   /plugin install bitbadges
# Cursor / Claude Desktop / other MCP clients:
#   claude mcp add bitbadges-builder -- npx -y -p bitbadges bitbadges-builder
```

See the full [Builder Tools Reference](/for-developers/ai-agents/builder-tools.md) for all 50+ tools (including session-based per-field builders), configuration for Claude Desktop / Cursor, and workflow guides.

## Network Configuration

| Network     | API URL                            | Node LCD                           | Cosmos Chain ID | EVM Chain ID | EVM RPC                                |
| ----------- | ---------------------------------- | ---------------------------------- | --------------- | ------------ | -------------------------------------- |
| **Mainnet** | `https://api.bitbadges.io`         | `https://lcd.bitbadges.io`         | `bitbadges-1`   | 50024        | `https://evm-rpc.bitbadges.io`         |
| **Testnet** | `https://api.bitbadges.io/testnet` | `https://lcd-testnet.bitbadges.io` | `bitbadges-2`   | 50025        | `https://evm-rpc-testnet.bitbadges.io` |
| **Local**   | `http://localhost:3001`            | `http://localhost:1317`            | `bitbadges-1`   | 90123        | `http://localhost:8545`                |

Additional endpoints (testnet):

* **RPC:** `https://rpc-testnet.bitbadges.io`
* **EVM RPC:** `https://evm-rpc-testnet.bitbadges.io`
* **WebSocket:** `wss://rpc-testnet.bitbadges.io/websocket`

## Section Contents

| Page                                                                                  | Description                                                |
| ------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| [Testnet Faucet API](/for-developers/ai-agents/testnet-faucet.md)                     | Get free testnet BADGE tokens for your bot                 |
| [Builder Tools Reference](/for-developers/ai-agents/builder-tools.md)                 | All 50+ builder tools for AI assistants                    |
| [WebSocket Events](/for-developers/ai-agents/websocket-events.md)                     | Subscribe to real-time blockchain events                   |
| [Bot Examples](/for-developers/ai-agents/bot-examples.md)                             | Copy-paste examples for common bot patterns                |
| [E2E: AI Agent with USDC Vault](/for-developers/ai-agents/openclaw-vault-tutorial.md) | Full tutorial: wallet setup, vault rules, withdraw/deposit |

## BB-402: Token-Gated API Access

BB-402 lets any server gate API access behind on-chain token ownership using the standard HTTP 402 status code. Unlike x402 (Coinbase) which only supports per-request USDC payments, BB-402 uses token ownership as a universal primitive -- a soulbound token costing X USDC is a verifiable on-chain receipt (equivalent to x402), but the same protocol also handles subscriptions, tiered access, reputation, blocklists, and compound conditions with `$and`/`$or` logic.

```
Agent --> Server:  GET /api/data
Server --> Agent:  402 { ownershipRequirements, message }
Agent --> Server:  GET /api/data + X-BB-Proof: { address, chain, message, signature }
Server --> Agent:  200 OK (or 403)
```

See the full [BB-402 guide and quickstart](/token-standard/bb-402/overview.md) in the Token Standard section, or the [complete specification](/token-standard/bb-402/spec.md).

## Further Reading

* [Signing Client Reference](/for-developers/create-and-broadcast-txs/signing-client.md) - Full signing client documentation
* [API Getting Started](/for-developers/bitbadges-api.md) - REST API reference
* [Testnet Mode](/for-developers/bitbadges-blockchain/testnet-mode.md) - Testnet environment details
* [BitBadges AI Quickstarter](https://github.com/BitBadges/bitbadges-quickstarter-ai) - GitHub template repo
* [SDK AI Agent Guide](https://github.com/BitBadges/bitbadgesjs/blob/main/packages/bitbadgesjs-sdk/AI_AGENT_GUIDE.md) - SDK-specific AI guide


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.bitbadges.io/for-developers/ai-agents.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.