Teardrop README

████████╗███████╗ █████╗ ██████╗ ██████╗ ██████╗  ██████╗ ██████╗
╚══██╔══╝██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔══██╗
   ██║   █████╗  ███████║██████╔╝██║  ██║██████╔╝██║   ██║██████╔╝
   ██║   ██╔══╝  ██╔══██║██╔══██╗██║  ██║██╔══██╗██║   ██║██╔═══╝
   ██║   ███████╗██║  ██║██║  ██║██████╔╝██║  ██║╚██████╔╝██║
   ╚═╝   ╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝ ╚═════╝ ╚═╝

Teardrop is a streaming API for applications and software agents to run tool-using AI workflows. Clients submit a message or task; Teardrop orchestrates a configured LLM (Anthropic, OpenAI, Google, or OpenRouter) and available tools, then streams structured results and UI events over Server-Sent Events (SSE). It supports AG-UI for streaming interaction, A2A for agent discovery and delegation, MCP for tool access, and optional x402 pay-per-request USDC settlement on Base.

Core Features

Agent-to-Agent (A2A) Delegation

Agents can discover opt-in specialists with the zero-cost discover_agents tool, including active published tool names, and securely delegate tasks via delegate_to_agent (both invoked during /agent/run). Features include allowlist control, JWT forwarding, per-run quotas, destination cost caps, optional advertised atomic-USDC task prices, and optional credit billing with org-level and caller-principal pause/24-hour spend-limit enforcement. A price above the effective allowlist cap returns error_type=advertised_price_exceeds_cap before funding; lower prices are rechecked against live budgets. Definitive non-delivery of a newly linked credit-funded delegation creates a reversal-linked refund, restoring the refunded amount to both rolling spend-cap calculations; ambiguous possibly_delivered calls remain held for explicit resolution. Refund rows created before migration 103 may be unlinked and restore balance without rolling-cap headroom.

For the full protocol specification, environment variables, allowlists, and billing event payloads, see docs/a2a-delegation.md.

Platform Tool Marketplace

Teardrop exposes 31 caller-facing built-in, metered tools through the marketplace catalog. Callers can invoke them:

• Via the MCP gateway at GET /tools/mcp (direct tool invocation, billed per call).
• As tools called during agent runs (via POST /agent/run when the agent decides to use them; billed in the run's usage cost).

For the complete list of tools, detailed descriptions, and their per-call prices, please refer to the docs/tools-catalog.md.

Enable with MARKETPLACE_ENABLED=true. When enabled, tools appear in GET /marketplace/catalog with qualified_name = "platform/{tool_name}" and tool_type = "platform". Catalog discovery supports category filtering, sort=popularity, single-tool detail pages, an author index at GET /marketplace/authors, author profiles, LLM-friendly discovery at GET /marketplace/llms.txt, and current effective prices at GET /marketplace/quote?tool={qualified_name}. The public catalog is the complete active published inventory for an author; authenticated agents can inspect their current org inventory at GET /agent/tools. The author index reports active published authors and aggregate call counts, then links clients to the existing author profile for tool details; it is not a list of remote A2A delegation URLs. Aggregate quality metrics are available at GET /.well-known/reputation.json. Marketplace authors can register external MCP servers and publish discovered tools as listings via POST /marketplace/import/preview and POST /marketplace/import/publish (organization admins or org-bound machine credentials).

MCP tools/list includes an observed-quality description for LLM clients and structured _meta["teardrop/reputation"] for programmatic clients when a tool has call history. The /tools/mcp surface lists platform tools (bare names, payable with x402 or credit) and published org tools ({org_slug}/{tool_name}, Bearer and credit only, listed only to Bearer callers), each with _meta["teardrop/price"]; the older /mcp/v1 surface is deprecated and sunsets on 2026-10-29. Catalog cost_usdc always equals the billed price on every surface; community tools with no author price use the platform default, and 0 means free. See docs/tools-catalog.md for the metadata contract.

Organizations can optionally publish one remote A2A endpoint in the public directory with PUT /marketplace/agent-registration, using an organization admin or an org-bound client-credentials token. Teardrop accepts HTTPS base URLs only, SSRF-checks them, discovers the remote Agent Card, and requires the /message:send endpoint used by the A2A client. The registry is separate from the outbound delegation allowlist: publishing makes an endpoint discoverable but does not authorize calls to it. GET /marketplace/agents lists opted-in endpoints with reputation metrics only after five distinct calling organizations; self-traffic, local failures, and ambiguous possibly_delivered outcomes are excluded. Its additive registered_at field is only a recency signal for new entrants and does not attest to quality or ownership. This machine-credential path covers endpoint registration and MCP tool publishing; withdrawal of earnings requires an organization admin or the owning SIWE wallet of a machine-provisioned organization.

Agent-owned webhook tools can be registered through POST /tools. Machine-provisioned organizations configure marketplace payouts through POST /marketplace/author-config with their owning SIWE wallet; the wallet is pinned to that identity unless an organization admin configures a treasury wallet. Author earnings recording no longer requires a payout configuration; self-calls remain excluded. Publishing new marketplace tools and requesting withdrawals still require a configured settlement wallet. Earnings recording remains best-effort, not a durable settlement-linked guarantee.

Platform tools are always available during agent runs, are not subscribable via POST /marketplace/subscriptions, and incur their marketplace prices (in addition to token costs). Per-org pricing overrides are supported via POST /admin/pricing/tools; for agent runs, tool_pricing_overrides takes precedence over marketplace catalog prices when both exist for the same tool.

Marketplace subscriptions are agent-run pins, not recurring payment plans or direct MCP access grants. Pinning selects a community tool for the org's /agent/run tool set; direct /tools/mcp calls do not require a pin and retain their authentication and billing requirements. In /agent/tools, the legacy access_mode="subscribed" means pinned, while "included" means no marketplace pin is needed, not free. Pins and inventory do not guarantee execution; see agent-run pins vs direct tool calls.

Marketplace Settlement & USDC Sweeping

Organizations can monetize their agents via a Marketplace. Withdrawals claim pending author earnings before sending USDC through Coinbase Developer Platform (CDP) to the configured settlement wallet. Confirmed transfers become settled; confirmed on-chain reverts release the earnings. Submission errors and unavailable confirmations remain in_flight, with earnings held to prevent automatic repayment. The sweep loop settles or releases in_flight withdrawals that recorded a transaction hash once that transaction is finalized and matches the claimed USDC transfer; operators must establish the chain outcome before resetting any other ambiguous withdrawal.

Auto-sweep is configured via MARKETPLACE_AUTO_SWEEP_ENABLED and related MARKETPLACE_* settings (see docs/configuration.md). Admin APIs: POST /admin/marketplace/sweep (manual sweep) and GET /admin/marketplace/settlement-balance.

Verified-Email Onboarding Credit

Teardrop can grant a small prepaid credit balance to newly verified organizations so a first agent run is possible without immediately setting up a wallet or card. This is disabled by default (ONBOARDING_CREDIT_ENABLED=false) and is intended only as a conversion aid, not as a source of withdrawable marketplace earnings.

The grant is awarded after a user consumes a single-use email verification token (GET /auth/verify-email). Token consumption, marking the user verified, and enqueueing eligibility are committed atomically; the grant is idempotent and retried by a background worker until it succeeds. Promotional credit can be used for platform tools, org webhook tools, MCP tools, and the base agent run cost, but cannot call marketplace author tools. A real top-up (Stripe, on-chain USDC, admin top-up, or refund) converts the org to normal credit status and removes the marketplace restriction. x402-paid SIWE calls are unaffected.

Check GET /billing/balance after verification to see the granted balance. See docs/configuration.md for the ONBOARDING_CREDIT_* settings.

Unattended (Scheduled) Agent Runs

Organizations can schedule recurring, unattended agent runs with integrated credit-only billing, stored execution history, and real-time status callbacks. Managed via the /agent/schedules API (POST/GET/PATCH/DELETE, plus GET /agent/schedules/{id}/runs for cursor-paginated results).

Due runs are claimed with a row-locking query (FOR UPDATE SKIP LOCKED) and execute concurrently with per-run failure isolation, so multiple worker instances can scale horizontally. Results are archived under scheduled_run_results and can be dispatched to an HTTPS-only, SSRF-checked callback URL. Use callback_format=text for a plain-text mobile notification; JSON remains the default. Configure via SCHEDULED_RUNS_* settings (see docs/configuration.md).

Scheduled analysis prompts can call the internal record_predictions tool with their exact structured payload and return only a concise narrative report. Teardrop labels those predictions asynchronously against future observations through the generalized labeling data plane; callbacks can therefore deliver the report to downstream notification systems while structured values remain available for ML evaluation. See docs/architecture.md and the LABELING_* settings in docs/configuration.md.

With VOR_ENABLED=true, external agents can also commit wallet-signed predictions through POST /labeling/predictions. Teardrop timestamps each prediction on the server, batches commitments into Merkle trees anchored on Base, and returns inclusion proofs from GET /labeling/predictions/{id}/proof. See the VOR_* settings in docs/configuration.md.

Pre-registered public tasks (currently oracle_deviation@1, which scores how far Chainlink ETH/USD drifts from a Uniswap v3 TWAP on Base) are scored from pinned, finalized on-chain reads. GET /scorecards/... publishes coverage-adjusted Brier scorecards without authentication; prediction payloads stay private.

Event-Triggered (Reactive) Runs

Beyond fixed intervals, organizations can register event triggers that run the agent in response to inbound webhooks (e.g. an on-chain event, a CRM update, a CI signal). An event trigger stores a prompt template; the inbound JSON payload is interpolated into it at dispatch time. Event triggers reuse the same execution core, credit billing, result history, and callback delivery as scheduled runs.

Managed via the /agent/event-triggers API (CRUD, secret rotation, and run polling). Inbound dispatch is POST /agent/events/{trigger_token}, authenticated with a per-trigger secret via the X-Teardrop-Trigger-Secret header, with optional idempotency keys and scalar-only, length-capped prompt interpolation to resist injection. Postgres execution leases enforce global and per-org concurrency (returning 429 when saturated).

Set next_trigger_id to another event trigger in the same organization to chain completed runs internally, without callback authentication. Chains are linear; EVENT_CHAIN_MAX_HOPS caps child hops (default: 2, allowing 3 runs including the root; 0 disables child dispatch). Results expose chain_id and zero-based hop_index. Child delivery is at most once: unavailable or saturated targets are audited and never retried.

Prompt templates interpolate untrusted payload data, so treat rendered prompts as untrusted input to the agent — scope event-trigger tools and credit limits accordingly. Configure via EVENT_TRIGGERS_* and EVENT_CHAIN_MAX_HOPS settings (see docs/configuration.md).

X (Twitter) Broadcast Posts

Organizations can configure scheduled runs to broadcast market analysis and opportunity verdicts directly to X (Twitter). Setting callback_format=x publishes the final output text to X via the v2 API using OAuth 1.0a authentication upon successful run completion, recording published tweet IDs in the immutable x_broadcasts audit ledger.

Broadcast runs require X_BROADCAST_ENABLED=true and a designated operator organization via X_BROADCAST_ORG_ID; schedules from any other organization are rejected with 403. To guard against elevated pay-per-usage API costs and phishing, output text containing URLs is rejected before publication. Configure via X_* settings (see docs/configuration.md).

Requirements

• Python 3.12+
• An API key for your chosen LLM provider: Anthropic, OpenAI, or Google AI (optional if using BYOK or self-hosted)
• A Postgres database (local via Docker, or Neon for production)
• Redis (optional, for caching — falls back to in-memory with TTL)

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:

powershellCopy

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

3. Install dependencies

pip install -r requirements.txt

4. Configure environment

Copy-Item .env.example .env

Minimum required contents:

# Global LLM provider fallback: anthropic | openai | google | openrouter (default: openrouter)
# Note: Each org can override via PUT /llm-config
AGENT_PROVIDER=openrouter
# Default model is ~deepseek/deepseek-flash-latest.
# For OpenRouter DeepSeek models, Teardrop delegates provider eligibility to the API key's OpenRouter data policy.
OPENROUTER_API_KEY=sk-or-...      # required if AGENT_PROVIDER=openrouter
# 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

# Optional: Redis for distributed caching
# REDIS_URL=redis://localhost:6379/0

5. Generate RSA keys

The RSA keypair is generated automatically at app startup (into keys/). To generate it manually first (optional), run:

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 teardrop.main: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 build --pull
docker compose up

Starts Postgres + Teardrop API. Migrations run automatically at startup. Keys are generated at build time and mounted from ./keys/. Use docker compose build --pull before rebuilds so refreshed base images are picked up, and add --no-cache when you want a fully fresh rebuild.

Render (production)

The repo includes a render.yaml that configures a single Standard (1c-2g) web service instance connected to Neon Postgres and your shared Redis service. The default database budget is 7 connections: up to six application-pool connections plus one LangGraph checkpointer connection per instance. Confirm that this leaves headroom under the configured Neon connection limit before deploying or increasing instance count.

For the comprehensive list of environment variables, security credentials, database configurations, and rate-limiting limits, please refer to the dedicated docs/configuration.md reference guide.

Authentication

Teardrop issues RS256 JWTs. Protected business endpoints require a Bearer token. Public auth, registration, billing-pricing, health, documentation, agent-card, and the payment-gated POST /message:send A2A surfaces remain unauthenticated as described below.

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.

3. SIWE — Sign-In with Ethereum

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 authenticate wallet identity, and new wallet addresses are auto-registered on first login. Machine-provisioned SIWE orgs use prepaid credit for agent runs; fund that credit through the agent funding loop below.

4. x402 payment-first bootstrap

An external agent can bootstrap an account without email, a human signup, or a prior JWT. Discover the flow from /.well-known/agent-card.json or the bootstrap block at /.well-known/x402 (also /.well-known/x402.json), then send POST /token with {"grant_type":"x402"}. Bootstrap discovery requires BILLING_ENABLED, MACHINE_PROVISIONING_ENABLED, and X402_ONBOARDING_ENABLED. Its payment requirements are separate from the top-level run-price accepts; discovery prices are advisory. The first token response is a 402 Payment Required containing the current x402 requirements for enough prepaid credit to pass the client-credential run reserve. Retry with the signed Payment-Signature (or legacy X-Payment) header.

On successful first settlement, Teardrop returns a short-lived access token plus a one-time client_id and client_secret. Store the secret immediately; it cannot be retrieved later. Use those credentials with the existing client-credentials /token flow for subsequent billable runs. Machine-provisioned orgs receive no promotional credit and start with the configured MACHINE_ORG_DAILY_SPEND_LIMIT_USDC rolling cap (default: $5.00 per 24 hours). An explicit operator-set org limit is preserved for trusted orgs; a zero stored limit resolves to the configured default.

Agent funding loop

Bootstrap once, then use the returned client credential to call GET /billing/topup/usdc/requirements?amount_usdc=... and sign the returned x402 requirements. Submit the signed header to POST /billing/topup/usdc before the prepaid balance is exhausted. Repeat grant_type=x402 payments are also accepted for an existing machine org; they reuse its client ID and omit client_secret. If the original secret is lost, authenticate with SIWE and use POST /org/credentials/regenerate.

Token expiry and refresh tokens

The email, client-credentials, and SIWE auth methods issue access tokens with a 30-minute expiry (expires_in: 1800 seconds in the token response). The x402 bootstrap also returns a 30-minute access token, but does not issue a refresh token. For applications that need sessions longer than 30 minutes, use refresh tokens from the email or SIWE flows:

• Refresh tokens expire after 30 days and can be exchanged for a new access token + rotated refresh token.
• Refresh token rotation is atomic with idempotency replay protection — if the same refresh token is submitted twice within the replay window, you'll receive the same new token pair instead of creating duplicates.
• Single logout via POST /auth/logout revokes your refresh token, ending the session immediately.

# 1. Exchange refresh token for new access token + rotated refresh token
$resp = Invoke-RestMethod -Uri "http://localhost:8000/auth/refresh" `
    -Method Post -ContentType "application/json" `
    -Headers @{ "Cookie" = "refresh_token=<your-refresh-token>" }
    # OR pass as body: -Body '{"refresh_token":"<your-refresh-token>"}'

# New access token and rotated refresh token are in the response
$newAccessToken = $resp.access_token
$newRefreshToken = $resp.refresh_token  # Use this on your next refresh

# 2. Logout (revoke refresh token)
Invoke-RestMethod -Uri "http://localhost:8000/auth/logout" `
    -Method Post -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $accessToken" }

LLM Configuration (Per-Org)

Organizations can configure their preferred LLM provider, model, routing strategy, and optionally bring their own API keys (BYOK). This unlocks:

• Multi-provider choice: Use Anthropic, OpenAI, Google, or point at self-hosted endpoints (vLLM, Ollama, OpenRouter)
• Bring Your Own Key (BYOK): Encrypt and store your own API credentials — Teardrop never sees your keys. BYOK orgs pay only platform orchestration fees (per-token when BYOK_TIER_PRICING_ENABLED=true, or a flat fee otherwise); the LLM provider is billed directly to their own key.
• Smart routing: Automatically select models based on cost, speed, or quality
• Self-hosted support: Use any OpenAI-compatible endpoint via api_base parameter

Org LLM config endpoints

Example: Set org's LLM to GPT-4o with cost-based routing

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

Invoke-RestMethod -Uri "http://localhost:8000/llm-config" `
    -Method Put -ContentType "application/json" `
    -Headers @{ Authorization = "Bearer $token" } `
    -Body @{
        provider = "openai"
        model = "gpt-4o"
        routing_preference = "cost"  # or "speed", "quality", "default"
        max_tokens = 4096
        temperature = 0.7
    } | ConvertTo-Json

For BYOK, add your own api_key (encrypted at rest). For self-hosted endpoints (vLLM, Ollama, or any OpenAI-compatible server), set api_base to your endpoint URL.

Reasoning hints are provider-specific: Google uses documented per-model thinking levels or budgets (none becomes low on Gemini 3.8 Flash); unknown Google model IDs retain provider defaults. OpenRouter receives reasoning.effort, subject to its model's supported efforts. Native OpenAI and Anthropic BYOK retain defaults. See reasoning effort compatibility for precedence and limits.

Routing preferences

When you set routing_preference to a value other than "default", Teardrop will automatically select a model from its standard pool based on your criteria:

Note: If you set BYOK (custom API key), routing is disabled — you always use your configured model.

LLM credit model

Teardrop prepaid credits (or on-chain x402 settlement) cover the full cost of every run, but the line item depends on whether the org uses platform LLM keys or BYOK:

Tool calls are priced the same way on every surface and for every model: admin override, then the author or platform price, then the global pricing_rules.tool_call_cost. Model-specific rules price tokens only. A rule with no per-unit rates is flat-rate: its run_price_usdc covers tokens once per run (not per LLM turn), and tool calls are billed on top.

On agent runs, a tool call is billed when it succeeds or returns a tool-reported business error (for example, an unknown protocol or wallet). Infrastructure failures are not billed: timeouts, upstream outages or rate limits, invalid upstream responses, invalid arguments, and unexpected executor errors.

In other words, BYOK does not eliminate the need for Teardrop credits or x402 settlement — it only removes the LLM model cost from the Teardrop bill.

Model Benchmarks

Teardrop continuously tracks operational metrics for every LLM deployed. These benchmarks inform model-routing decisions.

Benchmarks endpoints

Understanding the metrics

Each model entry includes catalogue metadata (provider, model, display_name, context_window, supports_tools, quality_tier, pricing) plus live benchmarks:

• total_runs_7d: Number of runs using this model in the last 7 days (benchmarks only included if >= 10 runs)
• avg_latency_ms: Average time (ms) from start to completion
• p95_latency_ms: 95th percentile latency — the slowest 5% of runs
• avg_cost_usdc_per_run: Average cost per run (input + output tokens + tools)
• avg_tokens_per_sec: Streaming throughput (useful for real-time applications)
• quality_tier: Static tier (1=best, 2=good) for quality-based routing

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

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.

An unpaid POST /agent/run returns a 402 Payment Required with the x402 v2 PaymentRequired envelope (PAYMENT-REQUIRED header, plus legacy X-PAYMENT-REQUIRED). The client signs the payment and retries with a Payment-Signature header; Teardrop verifies it with the facilitator, streams the SSE response, and emits a BILLING_SETTLEMENT event with the on-chain tx_hash after the run.

Payment methods by auth type

The x402 payment-first bootstrap charges a reserve-sized x402 payment, settles it before issuing credentials, and credits the resulting atomic-USDC amount to the new org. It does not use the verified-email promotional grant. Authenticated machine credentials can use the larger, less frequent /billing/topup/usdc balance top-up path instead of paying per run.

x402 payment schemes

upto client requirement: Before using X402_SCHEME=upto, the paying wallet must approve Permit2 for USDC on the target chain once: IERC20(USDC).approve(PERMIT2_ADDRESS, type(uint256).max). This is a one-time on-chain transaction per wallet. Clients that have not approved Permit2 can always use scheme: exact from the accepts array in the 402 response as a fallback.

Pricing

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

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

For the full set of billing environment variables (BILLING_ENABLED, X402_*, BILLABLE_AUTH_METHODS, etc.), see docs/configuration.md.

A2A Delegation & Cross-Agent Revenue Routing

Teardrop agents can delegate tasks to remote A2A-compliant agents and charge those delegations back to the calling organization. This unlocks decentralized specialisation, built-in spend orchestration, and automatic revenue routing.

The machine-readable /.well-known/registry-benefits.json contract explains how organizations register an A2A endpoint, what discovery and advisory reputation benefits they receive, and which guarantees are intentionally not provided.

For a detailed protocol specification, system configurations, allowlists, and billing event payload structures, see the docs/a2a-delegation.md guide.

Publishing to Agentic Market

Use the full public URL of the paid A2A surface, for example https://api.teardrop.dev/message:send, with method POST. Do not register the bare origin https://api.teardrop.dev/ (GET / redirects to /docs, and POST / is not a paid entrypoint).

Agentic Market validators may probe /.well-known/x402, /.well-known/x402.json, and the configured endpoint URL. Teardrop serves those discovery aliases publicly and issues the x402 challenge on unpaid anonymous POST /message:send requests before body validation. The challenge includes the full x402 v2 PaymentRequired envelope (PAYMENT-REQUIRED), a legacy X-PAYMENT-REQUIRED alias, a top-level resource describing the paid surface (url, description, and the shared Teardrop serviceName, tags, and iconUrl), and extensions.bazaar describing the A2A request/response shape.

The MCP endpoint POST https://api.teardrop.dev/tools/mcp behaves the same way for validators: an anonymous POST whose body is empty or not a JSON-RPC message, or an anonymous GET whose Accept header does not include text/event-stream, receives an HTTP 402 whose extensions.bazaar declares a paid tools/call example (get_token_price) and is priced at that tool's cost. Unpaid anonymous tools/call requests receive per-tool MCP Bazaar metadata, including the tool's output schema (top-level fields only when the full schema would exceed the 402 header budget). Every MCP 402 resource also carries Bazaar service metadata (serviceName, tags, and iconUrl from AGENT_CARD_ICON_URL when it is an absolute http(s) URL) so catalogs can label the listing. SSE GETs, authenticated requests, MCP handshakes, and tools/list stay on the normal MCP transport.

The Bazaar lists each MCP tool separately, and only after a payment for that tool settles through the CDP facilitator. python -m scripts.seed_bazaar_listings --base-url https://api.teardrop.dev quotes every paid tool without paying; add --execute with TEARDROP_SEED_PRIVATE_KEY set to make one settled call per tool. It stops at the first failure and refuses to pay if the gateway's 402 lacks Bazaar metadata or output declarations. The CDP facilitator drops serviceName, tags, and iconUrl from MCP-type records, so the Teardrop brand reaches catalogs such as Agentic.Market only through the HTTP /message:send listing, which carries the same metadata; seed it once with --a2a --execute.

Publishing to Smithery

Teardrop automatically advertises its MCP tools via /.well-known/mcp/server-card.json. To distribute on Smithery:

1. Copy the public base URL of your Teardrop instance into the Smithery URL Deployment wizard.
2. Provide the following Configuration Schema (JSON) inside the Smithery CLI or publish wizard to expose x402 anonymous capability:
   config.jsonCopy

   {
     "type": "object",
     "properties": {
       "apiKey": {
         "type": "string",
         "title": "API Key",
         "x-from": { "header": "x-teardrop-key" },
         "x-to": { "header": "Authorization" }
       }
     }
   }
   

3. Set the Display Name, Description, Homepage, and Icon within the Smithery dashboard to achieve the maximum 100/100 quality score.

Publishing to the MCP Registry

The official listing is io.github.HASAVAGE/teardrop at https://api.teardrop.dev/tools/mcp (Streamable HTTP, no package). Metadata lives in server.json at the repo root, and name must match the published namespace. To publish a new version: bump version and remotes in server.json, then from the repo root run mcp-publisher validate, mcp-publisher login github, and mcp-publisher publish.

API Reference

Teardrop provides interactive visual API explorers via OpenAPI at /docs (Swagger UI) and /redoc (ReDoc UI).

For a complete tabular list of all endpoints across Core, Auth, Billing, Marketplace, Wallets, Admin, Custom Tools, Memory, MCP Federation, and A2A Delegation surfaces, consult the docs/api-reference.md guide.

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

Teardrop uses portable agent nodes behind a LangGraph routing/checkpoint adapter and emits framework-neutral runtime events to its Server-Sent Events (SSE) layer.

For the complete architectural design, execution flow state diagrams, SSE stream event descriptions, and structured A2UI component schemas, consult the docs/architecture.md reference.

Database

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

Migrations

Active schema changes are in migrations/versions/. The current 102_squashed_baseline.sql replaces the historical files in migrations/archive/. Run migrations with:

python -m migrations.runner

For the active baseline, replacement manifest, and historical catalog of schema migrations, seed entries, and indexes, please refer to the docs/migrations.md catalog.

Neon (production)

Set DATABASE_URL to your Neon connection string. Plain postgresql:// is preferred; legacy postgresql+asyncpg:// values remain accepted.

Project structure

teardrop/
  app.py              # FastAPI app, lifespan, middleware, background workers, router registration
  main.py             # Compatibility entrypoint (re-exports teardrop.app)
  routers/            # APIRouter modules (agent.py, billing.py, marketplace.py, auth.py, admin/, org/, …)
  config.py           # Settings via pydantic-settings (reads .env)
  auth.py             # RS256 JWT & refresh tokens (email, client_credentials, SIWE)
  users/              # Org + User models, CRUD, PBKDF2-SHA256 password hashing
  billing/            # x402 billing layer, pricing, invoice queries, credit system
  marketplace/        # Marketplace catalog, earnings, reputation, subscriptions, withdrawals
  mcp_client/         # Per-org MCP client: CRUD, session pool, tool discovery
  org_tools/          # Per-org custom webhook tools: CRUD, caching, execution
  memory.py           # Per-org pgvector memory: LLM extraction, recall, CRUD
  agent/              # LangGraph graph, nodes, LLM factory, runtime context/events
  agent_runtime.py    # Agent run orchestration (scheduled/event-triggered runs)
  mcp_gateway.py      # MCP gateway middleware (direct tool invocation + billing)
tools/
  registry.py         # ToolRegistry: versioned, with deprecation lifecycle
  mcp_server.py       # Standalone MCPServer for MCP protocol clients
  definitions/        # One file per tool (calculate, get_datetime, web_search, …)
migrations/
  runner.py           # Applies active SQL migrations and squash baselines
  versions/           # Active SQL and .replaces manifests
  archive/            # Git-only historical migrations superseded by baselines
shared/               # Internal shared utilities: db pool registry, audit inserts, webhook caller
scripts/              # generate_keys.py, seed_users.py, audit_dependencies.py, export_api_spec.py, …

For the complete architectural design, execution flow state diagrams, SSE stream event descriptions, and structured A2UI component schemas, consult the docs/architecture.md reference.

Coinbase Developer Platform Integration

Teardrop can provision per-org USDC wallets via Coinbase Developer Platform (CDP) for receiving delegation payments and marketplace earnings. This requires a CDP account (cdp.coinbase.com) and an API key with wallet:create permission (Key ID, Key Secret, and Wallet Secret). Configure via the AGENT_WALLET_* and CDP_* environment variables (see docs/configuration.md). CDP charges $0.005 per operation; the free tier includes 5,000 ops/month.

Each org can hold one wallet per chain (e.g., Base Sepolia testnet, Base mainnet). Wallets auto-receive delegation payments and MCP marketplace earnings.

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.