Teardrop

████████╗███████╗ █████╗ ██████╗ ██████╗ ██████╗  ██████╗ ██████╗

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

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 was removed at its 2026-10-29 sunset. 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 a