https://github.com/GetBindu/Bindu
Bindu: The identity, communication, and payments layer for AI agents.
https://github.com/GetBindu/Bindu
a2a agent-communication agent-orchestration ai-agent autonomous-agents eu-ai-act machine-learning
Last synced: 6 days ago
JSON representation
Bindu: The identity, communication, and payments layer for AI agents.
- Host: GitHub
- URL: https://github.com/GetBindu/Bindu
- Owner: GetBindu
- License: other
- Created: 2025-03-16T22:37:03.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-28T14:44:10.000Z (18 days ago)
- Last Synced: 2026-05-28T16:04:16.165Z (18 days ago)
- Topics: a2a, agent-communication, agent-orchestration, ai-agent, autonomous-agents, eu-ai-act, machine-learning
- Language: Python
- Homepage: https://docs.getbindu.com
- Size: 47 MB
- Stars: 6,766
- Watchers: 9
- Forks: 387
- Open Issues: 136
-
Metadata Files:
- Readme: README.md
- Contributing: .github/contributing.md
- Funding: .github/FUNDING.yml
- License: LICENSE.md
- Security: docs/SECURITY_STACK.md
- Maintainers: maintainers.md
- Agents: AGENTS.md
Awesome Lists containing this project
- awesome - GetBindu/Bindu - Bindu: The identity, communication, and payments layer for AI agents. (Python)
README
Bindu
English |
Deutsch |
Español |
Français |
हिंदी |
বাংলা |
中文 |
Nederlands |
தமிழ்
The identity, communication, and payments layer for AI agents.
A Gmail-shaped inbox for the agent internet. Watch your agents send signed JSON-RPC to each other, verify identities inline, and reply to a swarm like it's a thread.
Here's the situation. You built an agent. It works. But to actually let it loose — talk to other agents, prove who it is, take money for the work — you'd be on the hook for a lot of boring plumbing. A DID library to integrate. An OAuth flow to set up. Payment middleware. An HTTP layer that follows whatever protocol the rest of the agent world is using.
Bindu is all of that plumbing, behind one function call. You wrap your handler with `bindufy()`, and a few seconds later your agent is online with its own cryptographic identity, speaking [A2A](https://github.com/a2aproject/A2A) (the protocol other agents already use), and ready to demand USDC on any EVM chain before it does any work ([x402](https://github.com/coinbase/x402)). Your handler stays as small as `(messages) -> response`. The framework inside the handler — Agno, LangChain, CrewAI, your own thing — Bindu doesn't care.
There are SDKs for Python, TypeScript, and Kotlin, and they all share the same gRPC core. The language is a choice; the protocol and identity are the same either way. When you're ready to go deeper, the [docs](https://docs.getbindu.com) are the next stop.
## Installation
You'll need Python 3.12+ and [uv](https://github.com/astral-sh/uv).
```bash
uv add bindu
```
If you're hacking on Bindu itself rather than using it:
```bash
git clone https://github.com/getbindu/Bindu.git
cd Bindu
uv sync --dev
```
To run the examples you'll need an API key for at least one LLM provider — `OPENROUTER_API_KEY`, `OPENAI_API_KEY`, or `MINIMAX_API_KEY`.
## Quickstart
Build the agent you want, hand it to `bindufy()`, and it's online. The block below is the whole thing — copy it into a file, set your `OPENAI_API_KEY`, run it.
```python
import os
from bindu.penguin.bindufy import bindufy
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from agno.tools.duckduckgo import DuckDuckGoTools
agent = Agent(
instructions="You are a research assistant.",
model=OpenAIChat(id="gpt-4o"),
tools=[DuckDuckGoTools()],
)
config = {
"author": "you@example.com",
"name": "research_agent",
"description": "Research assistant with web search.",
"deployment": {"url": "http://localhost:3773", "expose": True},
"skills": ["skills/question-answering"],
}
def handler(messages: list[dict[str, str]]):
return agent.run(input=messages)
bindufy(config, handler)
```
The agent is now live at `http://localhost:3773`. `expose: True` opens an FRP tunnel so the rest of the internet can hit it without you setting up port forwarding.
TypeScript equivalent
```typescript
import { bindufy } from "@bindu/sdk";
import OpenAI from "openai";
const openai = new OpenAI();
bindufy({
author: "you@example.com",
name: "research_agent",
description: "Research assistant.",
deployment: { url: "http://localhost:3773", expose: true },
skills: ["skills/question-answering"],
}, async (messages) => {
const response = await openai.chat.completions.create({
model: "gpt-4o",
messages: messages.map(m => ({ role: m.role as "user" | "assistant" | "system", content: m.content })),
});
return response.choices[0].message.content || "";
});
```
The TypeScript SDK spawns the Python core in the background — you won't see it, and you don't need any Python in your own codebase. Same protocol, same DID. Full example in [`examples/typescript-openai-agent/`](examples/typescript-openai-agent/).
Calling the agent with curl
```bash
curl -X POST http://localhost:3773/ \
-H 'Content-Type: application/json' \
-d '{
"jsonrpc": "2.0",
"method": "message/send",
"id": "",
"params": {
"message": {
"role": "user",
"kind": "message",
"parts": [{"kind": "text", "text": "Hello"}],
"messageId": "",
"contextId": "",
"taskId": ""
}
}
}'
```
Then poll `tasks/get` with the same `taskId` until state hits `completed`.
## Security: three layers, on by default
Most agent frameworks treat security as your problem. Bindu treats it as transport.
When an A2A request lands on a Bindu agent, three different middlewares fire before your handler sees the body — and each one answers a question the other two cannot:
| Layer | The question it answers | What it actually is |
|---|---|---|
| **mTLS** | _Is the socket itself encrypted and mutually authenticated?_ | X.509 cert from [Smallstep step-ca](https://smallstep.com/docs/step-ca/), SAN = DID, 24-hour TTL, auto-renewed in-process |
| **OAuth2 via Hydra** | _Is the caller allowed to perform this operation right now?_ | Ed-style bearer token, ~1-hour TTL, validated via [Ory Hydra](https://www.ory.sh/hydra/) introspection |
| **DID signature** | _Was this exact JSON body authored by the DID it claims?_ | Ed25519 signature over canonical body, carried in `X-DID-Signature` |
You don't pick one. You don't bolt them on. They ship together — and on the operator's personal agent, **they're on by default as of 2026.21.1**.
Why three layers, not one? Because each fails safe in a way the others can't:
- An attacker who steals a bearer token still can't decrypt your traffic — mTLS owns the wire.
- An attacker who somehow forges a cert still can't impersonate a DID — the signature won't verify against the claimed key.
- An attacker who breaks the signature scheme entirely still can't get past Hydra's authorization check.
The cert lives at the socket. The bearer token lives in the header. The signature lives in the body. Each one rejects a class of attack the others are blind to. **No agent framework we surveyed ships all three out of the box.**
→ **The full story:** [docs/SECURITY_STACK.md](docs/SECURITY_STACK.md) walks through what each layer does, how a single request flows through all three, today's defaults, the five real bugs we hit shipping default-on mTLS, and a troubleshooting matrix.
## Features
Every row here links out to the guide that actually goes into it.
| Feature | What it does | Docs |
|---|---|---|
| **A2A JSON-RPC** | The protocol other agents already speak. `message/send`, `tasks/get`, `message/stream` on port 3773. | — |
| **mTLS transport** | The socket is encrypted and mutually authenticated. Each agent gets a real X.509 cert from step-ca (SAN = DID), serves uvicorn over TLS, and renews itself every ~16 hours. On by default for the inbox personal agent in 2026.21.1. | [SECURITY_STACK.md](docs/SECURITY_STACK.md) · [MTLS_DEPLOYMENT_GUIDE.md](docs/MTLS_DEPLOYMENT_GUIDE.md) |
| **DID identity** | Every response your agent sends is signed with an Ed25519 key. Callers verify with a W3C DID — there's no shared secret to leak, no central authority to query, and the same DID is the cert's SAN, the OAuth2 client_id, and the message signer. All three have to agree, or the request is rejected. | [DID.md](docs/DID.md) |
| **OAuth2 via Hydra** | Scoped bearer tokens (`agent:read`, `agent:write`, `agent:execute`) instead of one key that opens every door. Each agent self-registers as a Hydra client at boot — its DID IS its client_id, so authorization, identity, and transport-layer cert all point at the same actor. | [AUTHENTICATION.md](docs/AUTHENTICATION.md) |
| **x402 payments** | Flip a flag and the agent demands USDC before your handler ever sees the request. **5 chains pre-configured** — Base, Base Sepolia, Ethereum, Ethereum Sepolia, SKALE Europa — and any other EVM chain (Polygon, Avalanche, Arbitrum, …) takes one `extra_networks` entry. | [PAYMENT.md](docs/PAYMENT.md) |
| **Push notifications** | The agent webhooks you when a task changes state. Stop polling. | [NOTIFICATIONS.md](docs/NOTIFICATIONS.md) |
| **Skills system** | Declare what your agent can do; callers see it on the agent card before they spend a token asking. | [SKILLS.md](docs/SKILLS.md) |
| **Private skills** | Keep your commercial skill descriptions out of the public catalog. Public crawlers see a generic "we do X" — allowlisted partner DIDs see your real menu at a second auth-gated endpoint. Useful when your skill descriptions ARE your product roadmap. | [PRIVATE_SKILLS.md](docs/PRIVATE_SKILLS.md) |
| **Agent negotiation** | Two agents agree on price, latency, and SLA up front. No surprise bills. | [NEGOTIATION.md](docs/NEGOTIATION.md) |
| **Storage** | Postgres for tasks and messages. Swap the backend if you've got a preference. | [STORAGE.md](docs/STORAGE.md) |
| **Scheduler** | Redis-backed retries, timeouts, and recurring tasks. | [SCHEDULER.md](docs/SCHEDULER.md) |
| **Public tunnel** | `expose: true` puts your laptop on the internet. No port forwarding, no router config. | [TUNNELING.md](docs/TUNNELING.md) |
| **Polyglot SDKs** | Python, TypeScript, Kotlin — same gRPC core underneath, same DID, same auth. | [GRPC_LANGUAGE_AGNOSTIC.md](docs/GRPC_LANGUAGE_AGNOSTIC.md) |
| **Cloud deploy** | `bindu deploy agent.py --runtime=boxd` ships your script to a microVM and prints the HTTPS URL. No Dockerfile. | [runtime/quickstart.md](docs/runtime/quickstart.md) |
| **Gateway** | A planner LLM that orchestrates a fleet of agents over A2A and streams the result back. | [GATEWAY.md](docs/GATEWAY.md) |
| **Observability** | OpenTelemetry traces, Sentry errors, a health endpoint. The boring stuff that saves you at 2am. | [OBSERVABILITY.md](docs/OBSERVABILITY.md) |
## Demo
The operator inbox at the top of this page is in [`inbox/`](inbox/README.md) — same auth, same DID signing, just visible. Run it with `cd inbox && npm run dev`.
## Examples
A handful from [`examples/`](examples/):
| Example | What it shows |
|---|---|
| [Agent Swarm](examples/agent_swarm/) | A small society of Agno agents passing work to each other. |
| [Premium Advisor](examples/premium-advisor/) | x402 in practice — the caller has to pay USDC before anything runs. |
| [Hermes via Bindu](examples/hermes_agent/) | Nous Research's Hermes agent, bindufied in ~90 lines. |
| [Gateway Test Fleet](examples/gateway_test_fleet/) | Five agents and one gateway — the multi-agent story end to end. |
| [TypeScript OpenAI Agent](examples/typescript-openai-agent/) | A TS-only agent with zero Python in your repo. |
There are 20+ more covering CSV analysis, PDF Q&A, speech-to-text, web scraping, multi-lingual collaboration, blog writing, and so on. Browse them in [`examples/`](examples/).
## Why we built Bindu
We're using Bindu in production to build the **Trade Compliance OS** — a swarm of agents that handles CBAM, EUDR, HS codes, and Digital Product Passports, so an SMB can ship coffee, textiles, or steel across borders without writing a six-figure check to a law firm. Every agent in that swarm is bindufied. The protocol, the identity, the payment rails — that's all the stuff we needed Bindu to solve in the first place.
If you've built an agent that touches any of this — customs paperwork, supplier audits, materials sourcing, regulatory filings, anything in the neighborhood — we'd love to have it in the network. [Come find us on Discord](https://discord.gg/3w5zuYUuwt) and let's talk.
## Supported frameworks
Bring whatever you already like writing agents in. Bindu doesn't care what's inside the handler.
| Language | Frameworks tested in this repo |
|---|---|
| **Python** | [AG2](https://github.com/ag2ai/ag2), [Agno](https://github.com/agno-agi/agno), [CrewAI](https://github.com/joaomdmoura/crewAI), [Hermes Agent](https://github.com/NousResearch/hermes-agent), [LangChain](https://github.com/langchain-ai/langchain), [LangGraph](https://github.com/langchain-ai/langgraph), [Notte](https://github.com/nottelabs/notte) |
| **TypeScript** | [OpenAI SDK](https://github.com/openai/openai-node), [LangChain.js](https://github.com/langchain-ai/langchainjs) |
| **Kotlin** | [OpenAI Kotlin SDK](https://github.com/aallam/openai-kotlin) |
| **Any other** | via the [gRPC core](docs/grpc/) — a new SDK is usually a few hundred lines |
If your model provider speaks the OpenAI or Anthropic API, it works — [OpenRouter](https://openrouter.ai/), [OpenAI](https://platform.openai.com/), [MiniMax](https://platform.minimaxi.com), and the rest.
## Documentation
- [Full docs site](https://docs.getbindu.com)
- [Security stack — mTLS + Hydra + DID](docs/SECURITY_STACK.md) — how the three identity layers compose, with a live walkthrough using the gateway test fleet
- [Calling a secured agent](docs/AUTH.md) — the shortest path: the two things you do when auth is on (token + DID signature), in one page
- [Auth — long form](docs/AUTHENTICATION.md) and [DID signing — long form](docs/DID.md) — when the short version isn't enough
- [mTLS deployment](docs/MTLS_DEPLOYMENT_GUIDE.md) — DevOps-facing guide for standing up step-ca, OIDC provisioner config, and the cert lifecycle
- [Cloud deployment](docs/runtime/quickstart.md) — `bindu deploy` walkthrough
- [Gateway](docs/GATEWAY.md) — multi-agent orchestration
- [Private skills](docs/PRIVATE_SKILLS.md) — hide your commercial menu from the public catalog; show it only to allowlisted partner DIDs
- [gRPC architecture](docs/grpc/) — for anyone building a new language SDK
- [Known issues](bugs/known-issues.md) — read this before you push to production
- [Troubleshooting](docs/AUTHENTICATION.md#troubleshooting) — the errors you'll hit, and how to get past them
## Testing
```bash
uv run pytest tests/unit/ -v # fast unit tests
uv run pytest tests/integration/grpc/ -v -m e2e # gRPC E2E
uv run pytest -n auto --cov=bindu --cov-report=term-missing # full suite
```
## Contributing
```bash
git clone https://github.com/getbindu/Bindu.git
cd Bindu
uv venv --python 3.12.9 && source .venv/bin/activate
uv sync --dev
pre-commit run --all-files
```
The full guide is in [`.github/contributing.md`](.github/contributing.md). Most of the day-to-day back-and-forth happens on [Discord](https://discord.gg/3w5zuYUuwt) — come say hi.
## Maintainers
Raahul Dutta
Paras Chamoli
Chandan
## Acknowledgements
Bindu stands on the shoulders of a lot of good open source:
[FastA2A](https://github.com/pydantic/fasta2a) · [A2A](https://github.com/a2aproject/A2A) · [x402](https://github.com/coinbase/x402) · [Hugging Face chat-ui](https://github.com/huggingface/chat-ui) · [12 Factor Agents](https://github.com/humanlayer/12-factor-agents) · [OpenCode](https://github.com/anomalyco/opencode) · [OpenMoji](https://openmoji.org/) · [ASCII Space Art](https://www.asciiart.eu/space/other)
## Star history
## License
Apache 2.0. See [LICENSE.md](LICENSE.md).
"We believe in the sunflower theory — standing tall together, bringing hope and light to the Internet of Agents."