Teardrop

@teardrop-ai

Visit Server

20 days ago

Streaming AI agent API built on LangGraph. Implements AG-UI, A2A, MCP, and x402 simultaneously. Agents discover it via A2A, call it over SSE, use its tools via MCP, and pay per request in USDC on Base. Per-org MCP federation, pgvector memory, 16 built-in Web3 tools, and dual billing (Stripe + x402).

Overview Tools Comments

Overview

teardrop

Intelligence beyond the browser

Teardrop is a streaming AI agent API. You send it a message; it reasons using your configured LLM (Anthropic, OpenAI, or Google), optionally calls tools, builds a structured UI component tree, and streams everything back as Server-Sent Events. It implements four open protocols simultaneously: AG-UI (streaming events), A2A (agent discoverability), MCP (tool serving), and x402 (per-request payments in USDC on Base, no subscription required).

Requirements

Python 3.11+
An API key for your chosen LLM provider: Anthropic, OpenAI, or Google AI
A Postgres database (local via Docker, or Neon for production)

Setup (PowerShell)

1. Clone and enter the project

git clone https://github.com/teardrop-ai/teardrop.git
cd teardrop

2. Create and activate a virtual environment

python -m venv venv
.\venv\Scripts\Activate.ps1

If you get a script execution error, run first:
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

Copy-Item .env.example .env

Minimum required contents:

# LLM provider: anthropic | openai | google (default: anthropic)
AGENT_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-...      # required if AGENT_PROVIDER=anthropic
# OPENAI_API_KEY=sk-...           # required if AGENT_PROVIDER=openai
# GOOGLE_API_KEY=...              # required if AGENT_PROVIDER=google

DATABASE_URL=postgresql://teardrop:teardrop@localhost:5432/teardrop

5. Generate RSA keys

python scripts/generate_keys.py

6. Run database migrations

python -m migrations.runner

7. Seed default org and admin user

python scripts/seed_users.py

8. Run the API server

uvicorn app:app --reload

Server starts at http://localhost:8000. Visit http://localhost:8000/docs for the interactive API explorer.

Deployment

Docker (local full stack)

docker-compose up --build

Starts Postgres + Teardrop API. Migrations run automatically at startup. Keys are generated at build time and mounted from ./keys/.

Render (production)

The repo includes a render.yaml that configures a Render web service. Set these environment variables in the Render dashboard:

Variable	Description
`AGENT_PROVIDER`	`anthropic`, `openai`, or `google` (default: `anthropic`)
`ANTHROPIC_API_KEY`	Required if `AGENT_PROVIDER=anthropic`
`OPENAI_API_KEY`	Required if `AGENT_PROVIDER=openai`
`GOOGLE_API_KEY`	Required if `AGENT_PROVIDER=google`
`DATABASE_URL`	Neon Postgres connection string
`BILLING_ENABLED`	`true` to activate x402 payments
`X402_PAY_TO_ADDRESS`	Treasury wallet (USDC recipient)
`X402_NETWORK`	`eip155:8453` for Base mainnet
`SIWE_DOMAIN`	Your public domain (e.g. `teardrop.onrender.com`)
`CORS_ORIGINS`	Comma-separated allowed origins

Authentication

Teardrop issues RS256 JWTs. All endpoints (except /health, /docs, /billing/pricing, /.well-known/agent-card.json) require a Bearer token.

1. Client credentials (machine-to-machine)

$resp = Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"client_id":"teardrop-client","client_secret":"<JWT_CLIENT_SECRET>"}'
$token = $resp.access_token

The resulting JWT includes auth_method: "client_credentials". Set JWT_CLIENT_ID and JWT_CLIENT_SECRET in .env.

2. Email + password

$resp = Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"email":"admin@example.com","secret":"<password>"}'

The resulting JWT includes auth_method: "email". Create users via POST /admin/users.

SIWE lets Ethereum wallet holders authenticate without a password. The JWT issued includes auth_method: "siwe" and the caller's address.

1. GET  /auth/siwe/nonce   → { "nonce": "abc123..." }
2. Construct an EIP-4361 SIWE message with that nonce
3. Sign with your wallet (EIP-191)
4. POST /token  { "siwe_message": "...", "siwe_signature": "0x..." }
   → { "access_token": "..." }

SIWE tokens are the only auth method that can use x402 on-chain payments. New wallet addresses are auto-registered on first login.

Billing & Payments (x402)

Teardrop implements the x402 payment protocol. When BILLING_ENABLED=true, requests must include payment. Set BILLING_ENABLED=false (default) to run without billing during development.

How it works

Client                         Teardrop                     x402 Facilitator
  │                               │                               │
  │── POST /agent/run ───────────►│                               │
  │   (no payment header)         │                               │
  │◄── 402 Payment Required ──────│                               │
  │    X-PAYMENT-REQUIRED: <reqs> │                               │
  │                               │                               │
  │── POST /agent/run ───────────►│                               │
  │   Payment-Signature: <signed> │── verify payment ────────────►│
  │                               │◄─ verified ───────────────────│
  │◄── SSE stream ────────────────│                               │
  │   (TEXT, TOOL, SURFACE...)    │                               │
  │   BILLING_SETTLEMENT          │── settle on-chain ───────────►│
  │   { tx_hash, amount_usdc }    │◄─ tx confirmed ───────────────│

Payment methods by auth type

Auth method	Payment mechanism
`siwe`	x402 on-chain (USDC, `exact` scheme, per-request)
`client_credentials`	Org prepaid credit balance (off-chain debit)
`email`	Org prepaid credit balance (off-chain debit)

Configuration

BILLING_ENABLED=true
X402_PAY_TO_ADDRESS=0xYourTreasuryWallet
X402_NETWORK=eip155:8453          # Base mainnet (eip155:84532 = Base Sepolia)
X402_FACILITATOR_URL=https://x402.org/facilitator
BILLABLE_AUTH_METHODS=["siwe"]    # Add "client_credentials","email" to bill those too

Pricing

Pricing is dynamic via the pricing_rules database table. Current rates (usage-based v1):

Metric	Rate
Input tokens	$0.0015 / 1k tokens
Output tokens	$0.0075 / 1k tokens
Tool calls	$0.001 / call
Minimum per run	$0.01

Check live pricing: GET /billing/pricing

Running as x402 client (SIWE payments)

# 1. Get a SIWE JWT (see Authentication above)
# 2. Call /agent/run — you'll get a 402 with payment requirements
# 3. Construct and sign the x402 transferWithAuthorization (EIP-3009)
# 4. Retry with the signed payment header

Invoke-RestMethod -Uri "http://localhost:8000/agent/run" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token"; "Payment-Signature" = "<x402-header>" } `
    -Body '{"message":"What is the ETH balance of vitalik.eth?","thread_id":"session-1"}'

The stream will include a BILLING_SETTLEMENT event with the on-chain tx_hash after the run completes.

Credit top-up (machine callers)

Admins can add prepaid USDC credit to an org's balance:

Invoke-RestMethod -Uri "http://localhost:8000/admin/credits/topup" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $adminToken" } `
    -Body '{"org_id":"org-123","amount_usdc":1000000}'   # $1.00

API reference

Core

Method	Path	Auth	Description
`GET`	`/`	—	Redirects to `/docs`
`GET`	`/health`	—	Liveness probe
`POST`	`/agent/run`	Bearer	Main streaming endpoint (SSE)
`GET`	`/.well-known/agent-card.json`	—	A2A agent card
`GET`	`/docs`	—	Swagger UI
`GET`	`/redoc`	—	ReDoc UI

Auth

Method	Path	Auth	Description
`POST`	`/token`	—	Issue JWT (client-creds, email, or SIWE)
`GET`	`/auth/me`	Bearer	Return the authenticated user's identity
`GET`	`/auth/siwe/nonce`	—	Generate single-use SIWE nonce

Billing

Method	Path	Auth	Description
`GET`	`/billing/pricing`	—	Current pricing rules
`GET`	`/billing/history`	Bearer	Settled payment history (cursor paginated)
`GET`	`/billing/invoices`	Bearer	All run records including pending (cursor paginated)
`GET`	`/billing/invoice/{run_id}`	Bearer	Single run receipt
`GET`	`/billing/balance`	Bearer	Org prepaid credit balance
`GET`	`/billing/credit-history`	Bearer	Credit ledger — top-ups and debits (cursor paginated)
`POST`	`/billing/topup/stripe`	Bearer	Start a Stripe checkout session to add credits
`GET`	`/billing/topup/stripe/status`	Bearer	Check Stripe checkout session status
`GET`	`/billing/topup/usdc/requirements`	Bearer	Get on-chain USDC top-up payment requirements
`POST`	`/billing/topup/usdc`	Bearer	Submit and verify an on-chain USDC top-up

Wallets

Method	Path	Auth	Description
`POST`	`/wallets/link`	Bearer	Link additional wallet via SIWE
`GET`	`/wallets/me`	Bearer	List your linked wallets
`DELETE`	`/wallets/{wallet_id}`	Bearer	Unlink a wallet

Usage

Method	Path	Auth	Description
`GET`	`/usage/me`	Bearer	Aggregated token/tool usage for current user

Admin

Method	Path	Auth	Description
`POST`	`/admin/orgs`	Admin	Create organisation
`POST`	`/admin/users`	Admin	Create user
`POST`	`/admin/client-credentials`	Admin	Create M2M client credentials for an org
`GET`	`/admin/usage/{user_id}`	Admin	Usage for a specific user
`GET`	`/admin/usage/org/{org_id}`	Admin	Usage for an org
`GET`	`/admin/billing/revenue`	Admin	Aggregated revenue summary
`POST`	`/admin/credits/topup`	Admin	Add prepaid USDC credits to an org
`POST`	`/admin/pricing/tools`	Admin	Create or update a per-tool pricing override
`DELETE`	`/admin/pricing/tools/{tool_name}`	Admin	Remove a per-tool pricing override
`GET`	`/admin/tools/{org_id}`	Admin	List custom tools for an org
`GET`	`/admin/memories/org/{org_id}`	Admin	List memories for an org
`DELETE`	`/admin/memories/org/{org_id}`	Admin	Delete all memories for an org
`GET`	`/admin/mcp/servers/{org_id}`	Admin	List MCP servers for an org

Custom Tools

Per-org webhook-backed tools are injected into the agent at run-time and never appear in the public Agent Card or MCP server.

Method	Path	Auth	Description
`POST`	`/tools`	Bearer	Register a custom webhook tool
`GET`	`/tools`	Bearer	List org's custom tools
`GET`	`/tools/{tool_id}`	Bearer	Get a specific custom tool
`PATCH`	`/tools/{tool_id}`	Bearer	Update a custom tool
`DELETE`	`/tools/{tool_id}`	Bearer	Delete a custom tool

Memory

Per-org persistent memory backed by pgvector. Memories are extracted automatically during agent runs and recalled as context on subsequent turns.

Method	Path	Auth	Description
`GET`	`/memories`	Bearer	List org memories (cursor paginated)
`POST`	`/memories`	Bearer	Store a memory manually
`DELETE`	`/memories/{memory_id}`	Bearer	Delete a specific memory

MCP Federation

Connect external MCP servers to your org. Their tools are discovered and made available to the agent alongside the built-in tool set.

Method	Path	Auth	Description
`POST`	`/mcp/servers`	Bearer	Register an external MCP server
`GET`	`/mcp/servers`	Bearer	List org's MCP servers
`GET`	`/mcp/servers/{server_id}`	Bearer	Get a specific MCP server
`PATCH`	`/mcp/servers/{server_id}`	Bearer	Update an MCP server
`DELETE`	`/mcp/servers/{server_id}`	Bearer	Remove an MCP server
`POST`	`/mcp/servers/{server_id}/discover`	Bearer	Trigger tool re-discovery from an MCP server

Calling the agent (PowerShell)

$token = (Invoke-RestMethod -Uri "http://localhost:8000/token" `
    -Method Post -ContentType "application/json" `
    -Body '{"client_id":"teardrop-client","client_secret":"<secret>"}').access_token

$body = '{"message": "What is 42 * 7?", "thread_id": "my-session-1"}'
Invoke-RestMethod -Uri "http://localhost:8000/agent/run" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Body $body

For multi-turn conversation, reuse the same thread_id across requests.

Pagination

/billing/history, /billing/invoices, /billing/credit-history, and /memories support cursor-based pagination:

GET /billing/invoices?limit=50
→ { "items": [...], "next_cursor": "2026-04-01T12:00:00.000Z" }

GET /billing/invoices?limit=50&cursor=2026-04-01T12:00:00.000Z
→ { "items": [...], "next_cursor": null }   # no more pages

Running the MCP tool server (optional)

The tools can be served standalone over the MCP protocol for use with Claude Desktop, VS Code, or any MCP-compatible client:

# stdio transport (default – for Claude Desktop / VS Code)
python tools/mcp_server.py

# HTTP SSE transport
python tools/mcp_server.py --transport=sse

How it works

Agent graph (`agent/graph.py`)

The agent runs as a LangGraph state machine with three nodes:

START → planner → [tool_executor ↩] → ui_generator → END

planner — Sends the conversation to the configured LLM with all tools bound. If the LLM decides to call a tool, status is set to EXECUTING; otherwise it moves to UI generation.
tool_executor — Runs all pending tool calls in parallel, appends ToolMessage results, then loops back to the planner for further reasoning.
ui_generator — Extracts or generates A2UI component JSON from the final assistant message and attaches it to the state.

Conversation history persists across turns via AsyncPostgresSaver (Postgres-backed LangGraph checkpointer).

Streaming (`app.py`)

POST /agent/run returns a live SSE stream. Event types emitted:

Event	When
`RUN_STARTED`	Immediately on request
`TEXT_MESSAGE_CONTENT`	Each LLM token chunk
`TOOL_CALL_START`	Before a tool executes
`TOOL_CALL_END`	After a tool returns
`SURFACE_UPDATE`	When A2UI components are ready
`BILLING_SETTLEMENT`	After on-chain payment settles
`USAGE_SUMMARY`	Total tokens, tools, cost for the run
`RUN_FINISHED`	Agent completed normally
`ERROR`	Unhandled exception
`DONE`	Stream closed

Tools (`tools/definitions/`)

Sixteen tools are available to the agent and served via MCP:

Tool	Description
`calculate`	Evaluates arithmetic expressions safely (no `eval`). Supports `+`, `-`, ``, `/`, `*`, `%`, `sqrt`, `abs`, `round`, `floor`, `ceil`, `log`, `sin`, `cos`, `tan`, `pi`, `e`.
`convert_currency`	Converts between fiat and crypto currencies using CoinGecko and live fiat exchange rates.
`decode_transaction`	Decodes transaction calldata into human-readable form using the supplied ABI or 4byte.directory.
`get_block`	Block metadata (timestamp, gas, miner, tx count) by number or `"latest"`.
`get_datetime`	Returns current UTC date/time. Accepts an optional `strftime` format string.
`get_erc20_balance`	ERC-20 token balance for an address.
`get_eth_balance`	ETH balance for an Ethereum address (mainnet or Base). Requires `ETHEREUM_RPC_URL` or `BASE_RPC_URL`.
`get_gas_price`	Current gas price (gwei) and EIP-1559 fee components on Ethereum or Base.
`get_token_price`	Crypto asset price in USD (or any supported currency) via CoinGecko.
`get_transaction`	Transaction details and status by hash.
`get_wallet_portfolio`	Aggregated token holdings and USD value for an Ethereum or Base wallet.
`http_fetch`	Fetches and extracts content from a URL. Includes SSRF protection — private/cloud-metadata IPs are blocked.
`read_contract`	Calls `view`/`pure` functions on any smart contract by ABI fragment.
`resolve_ens`	Resolves ENS name → address or address → ENS primary name.
`summarize_text`	Returns character, word, sentence, and paragraph counts for a given text.
`web_search`	Web search via Tavily. Set `TAVILY_API_KEY` to activate.

A2UI components (`agent/state.py`)

The agent can return structured UI alongside text. Supported component types:

Type	Props
`text`	`content`, `variant` (`body`\|`heading`\|`caption`)
`table`	`columns`, `rows`
`columns`	`children`
`rows`	`children`
`form`	`fields`, `submit_label`
`button`	`label`, `action`
`progress`	`value` (0–100), `label`

Database

Teardrop uses Postgres (Neon recommended for production, local via Docker for development).

Migrations

All schema changes are in migrations/versions/. Run them with:

python -m migrations.runner

File	Contents
`001_baseline.sql`	Core tables: `orgs`, `users`, `wallets`, `siwe_nonces`, `usage_events`
`002_billing.sql`	Adds billing fields to `usage_events`; creates `pricing_rules`
`003_pricing_seed.sql`	Seeds default usage-based pricing (tokens_in, tokens_out, tool_call rates)
`004_credits.sql`	Adds `org_credits` table for prepaid credit balances
`005_org_client_credentials.sql`	Per-org M2M client credentials (`org_client_credentials`)
`006_credit_ledger.sql`	Immutable debit/top-up audit trail (`org_credit_ledger`)
`007_stripe_webhook_events.sql`	Stripe webhook idempotency table (`stripe_webhook_events`)
`008_usdc_topup_events.sql`	USDC on-chain top-up events (`usdc_topup_events`)
`009_tool_pricing_overrides.sql`	Per-tool pricing overrides; seeds web_search, get_token_price, get_wallet_portfolio rates
`010_org_tools.sql`	Per-org custom webhook tools (`org_tools`) and audit events
`011_org_memories.sql`	Enables `pgvector`; creates `org_memories` table with HNSW index
`012_org_mcp_servers.sql`	Per-org MCP server connections (`org_mcp_servers`) and audit events

Neon (production)

Set DATABASE_URL to your Neon connection string (no +asyncpg prefix needed — the app strips it automatically).

Project structure

app.py              # FastAPI app, SSE streaming, billing gate, all route handlers
auth.py             # RS256 JWT: create_access_token, require_auth dependency
billing.py          # x402 billing layer, pricing, invoice queries, credit system
cache.py            # Redis cache helpers
config.py           # Settings via pydantic-settings (reads .env)
memory.py           # Per-org pgvector memory: LLM extraction, recall, CRUD
mcp_client.py       # Per-org MCP client: CRUD, session pool, tool discovery
org_tools.py        # Per-org custom webhook tools: CRUD, caching, execution
usage.py            # UsageEvent model, usage recording and aggregation
users.py            # Org + User models, CRUD, PBKDF2-SHA256 password hashing
wallets.py          # Wallet management, SIWE nonce lifecycle
agent/
  graph.py          # LangGraph StateGraph definition and routing
  llm.py            # Multi-provider LLM factory (Anthropic, OpenAI, Google)
  nodes.py          # planner, tool_executor, ui_generator implementations
  state.py          # AgentState, A2UIComponent, TaskStatus schemas
tools/
  registry.py       # ToolRegistry: versioned, with deprecation lifecycle
  mcp_server.py     # Standalone FastMCP server for MCP protocol clients
  definitions/      # One file per tool (calculate, get_datetime, web_search, …)
  __init__.py       # Global registry singleton, get_langchain_tools()
migrations/
  runner.py         # Applies SQL migrations in order
  versions/         # 001_baseline through 012_org_mcp_servers
scripts/
  generate_keys.py  # Generate RSA keypair → keys/private.pem + keys/public.pem
  init_neon.py      # Initialize Neon Postgres schema
  seed_users.py     # Create default org + admin user for local dev

License

Teardrop is licensed under the Business Source License 1.1.

Free to use for non-production evaluation and development.
Commercial production use requires a commercial license from the maintainer.
Change Date: April 3, 2030 — on this date the code automatically converts to AGPL-3.0-only.

See LICENSE for full terms. For commercial licensing enquiries, see the contact address in the LICENSE file.

Contributions are welcome under the same license — see CONTRIBUTING.md. To report a security vulnerability, see SECURITY.md.

Try in Playground

Server Config

{
  "mcpServers": {
    "teardrop": {
      "url": "https://teardrop.onrender.com/tools/mcp"
    }
  }
}

Build with ShipAny.

Teardrop

teardrop

Requirements

Setup (PowerShell)

Deployment

Docker (local full stack)

Render (production)

Authentication

1. Client credentials (machine-to-machine)

2. Email + password

3. SIWE — Sign-In with Ethereum

Billing & Payments (x402)

How it works

Payment methods by auth type

Configuration

Pricing

Running as x402 client (SIWE payments)

Credit top-up (machine callers)

API reference

Core

Auth

Billing

Wallets

Usage

Admin

Custom Tools

Memory

MCP Federation

Calling the agent (PowerShell)

Pagination

Running the MCP tool server (optional)

How it works

Agent graph (agent/graph.py)

Streaming (app.py)

Tools (tools/definitions/)

A2UI components (agent/state.py)

Database

Migrations

Neon (production)

Project structure

License

Server Config

Agent graph (`agent/graph.py`)

Streaming (`app.py`)

Tools (`tools/definitions/`)

A2UI components (`agent/state.py`)