A2A-SE adds escrow-based payment to the A2A protocol in under 100 lines of integration code. When two agents discover each other through A2A and one performs work for the other, A2A-SE holds funds in escrow during task execution and releases them on completion -- or refunds them on failure. Zero modifications to A2A core. Currency-agnostic. The exchange is an interface, not a service: agents can point to any conforming implementation (hosted, self-hosted, or on-chain).
RequesterAgent <---- A2A ----> ProviderAgent
| |
+--------- HTTPS (A2A-SE) ------+
Exchange
escrow / release / refund
Test agent payments without running any infrastructure. The public sandbox at https://sandbox.a2a-settlement.org gives you starter credits on registration.
git clone https://github.com/a2a-settlement/a2a-settlement
cd a2a-settlement
pip install -e ./sdk
A2A_EXCHANGE_URL=https://sandbox.a2a-settlement.org python examples/quickstart.pyYou should see an escrow created and released, and balances updated. Registration is open; no API key needed beforehand — the quickstart registers two demo accounts and runs a full escrow cycle.
To run the exchange locally instead:
git clone https://github.com/a2a-settlement/a2a-settlement
cd a2a-settlement
pip install -e ./sdk
python exchange/app.py &
python examples/quickstart.pyYou should see an escrow created and released, and balances updated.
| Language | Package | Install |
|---|---|---|
| Python | a2a-settlement |
pip install -e ./sdk |
| TypeScript/JS | @a2a-settlement/sdk |
cd sdk-ts && npm install |
Both SDKs mirror the same method signatures. See sdk/ and sdk-ts/ for docs.
Docker Compose (recommended):
docker compose up -d
curl http://localhost:3000/healthFly.io:
fly launch --copy-config
fly postgres create --name a2a-exchange-db
fly postgres attach a2a-exchange-db
fly deployRailway: Fork the repo, connect Railway, add the PostgreSQL plugin, deploy.
See docs/self-hosting.md for full environment variable reference.
Optional integrations: Add a2a-settlement-auth middleware for OAuth-based economic authorization and the Secret Vault. Run the Security Shim (shim/) for escrow-gated external tool access with credential injection (the Economic Air Gap). Run a2a-settlement-mediator as a sidecar for AI-powered dispute resolution. Use a2a-settlement-dashboard for human oversight. Train agents against live bounties using the Self-Improving Agent Loop before deploying to production.
SPEC.md-- the extension specification (v0.8.1)openapi.yaml-- OpenAPI 3.1 spec for the exchange APIexchange/-- FastAPI + SQLAlchemy settlement exchange (SQLite dev, Postgres prod)shim/-- Security Shim forward proxy (Economic Air Gap -- escrow-gated tool access with credential injection)sdk/-- pip-installable Python SDKsdk-ts/-- npm-installable TypeScript/JavaScript SDKexamples/-- runnable demos (including air gap three-act demo)docs/-- architecture, integration guide, economic air gap, pricing models, self-hosting, self-improving agentsDockerfile+docker-compose.yml-- containerized deploymentfly.toml+railway.json-- one-click cloud deploy configs
These three protocols address different layers of the agent payment stack. They are complementary, not competing.
- x402 is an access gate: pay-per-call micropayments to talk to an agent. Think of it as a toll booth.
- AP2 (Agent Payments Protocol) handles payment negotiation: "how will we pay?" It defines flows for agents to agree on payment methods and amounts.
- A2A-SE handles task escrow: "hold these funds while I work, then release them." It provides escrow, multi-step settlement, dispute resolution, and reputation tracking.
| Concern | AP2 | x402 | A2A-SE |
|---|---|---|---|
| Payment negotiation | Yes | -- | Lightweight |
| Access gating | -- | Yes | -- |
| Task escrow | -- | -- | Yes |
| Dispute resolution | -- | -- | Yes |
| Reputation | -- | -- | Yes |
| Multi-turn tasks | -- | -- | Yes |
An agent can use all three: x402 gates discovery, AP2 negotiates terms, A2A-SE escrows the payment.
The a2a-settlement bridge serves as the authoritative security layer between autonomous agents (LangGraph, CrewAI, LiteLLM) and sensitive infrastructure. It mitigates Agent-on-Agent (A2A) attacks—such as the hackerbot-claw exploit—by replacing static API permissions with dynamic, reputation-gated execution.
| Primitive | Description |
|---|---|
| Reputation-Gated Execution (EMA) | Every agent action is filtered through an Exponential Moving Average trust score. High-risk tools (Shell, PR Merge, Cloud Console) require a minimum |
| Ephemeral AgentCards | Replaces persistent environment variables with task-specific, cryptographically signed identities. These cards define a strict "Intent Scope"—any command execution outside this scope (e.g., unauthorized curl to metadata services) results in immediate credential revocation. |
| Security-Weighted CBS | The Composite Bid Score (CBS) forces a trade-off between performance and security. For mission-critical tasks, the bridge prioritizes agents with high Verifiable Logic Proofs ( |
| Logic Verifiability Layer | Before an action is committed to the bridge, the agent must submit a "pre-flight" logic proof. The settlement layer validates this against defined safety policies, preventing "hallucinated" or malicious privilege escalations. |
| Threat Vector | a2a-settlement Mitigation |
|---|---|
| Privilege Escalation | EMA Thresholding prevents unvetted agents from accessing sudo/shell. |
| Identity Hijacking | AgentCards ensure only the specific "Identified Agent" can execute the signed task. |
| Payload Injection | Logic Proofs require the agent to declare intent before writing to a repo/pipeline. |
| Lateral Movement | Settlement Isolation freezes an agent's status across the entire network upon a single dispute. |
When the exchange is running (locally or sandbox), visit:
- Sandbox Swagger UI: https://sandbox.a2a-settlement.org/docs
- Sandbox ReDoc: https://sandbox.a2a-settlement.org/redoc
- Local: http://localhost:3000/docs and http://localhost:3000/redoc
Or see openapi.yaml in the repo root for the normative spec.
pip install -e ".[exchange,examples,dev]"
pytest -q| Project | Description |
|---|---|
| a2a-settlement-auth | OAuth 2.0 settlement scopes — spending limits, counterparty policies, delegation chains |
| a2a-settlement-mediator | AI-powered dispute resolution — auto-resolves clear cases, escalates ambiguous ones |
| a2a-settlement-dashboard | Human oversight dashboard — monitor spending, audit transactions, revoke authority |
| a2a-settlement-mcp | MCP server — settlement tools for Claude, Cursor, LangGraph, or any MCP client |
| settlebridge-ai | SettleBridge Gateway — trust/policy enforcement + bounty marketplace |
| mcp-trust-gateway | MCP Trust Gateway — trust, reputation, and economic accountability above OAuth |
| otel-agent-provenance | OpenTelemetry semantic conventions for agent provenance and derivation lineage |
| a2a-federation-rfc | Federation protocol — interoperable reputation and settlement across exchanges |
| Project | Framework | Pattern |
|---|---|---|
| langgraph-a2a-settlement | LangGraph | Escrow-gated graph nodes, create_settlement_graph |
| crewai-a2a-settlement | CrewAI | SettledCrew / SettledTask wrappers |
| litellm-a2a-settlement | LiteLLM | Callback hooks for escrow on A2A agent calls |
| adk-a2a-settlement | Google ADK | to_settled_a2a, SettledRemoteAgent, settlement tools |
Environment variables: Most integrations use A2A_EXCHANGE_URL (e.g. http://localhost:3000) and A2A_API_KEY. ADK and CrewAI use A2ASE_EXCHANGE_URL / A2ASE_API_KEY. The exchange API lives under /v1; the SDK appends this automatically.
MIT. See LICENSE.