DOCSEARCHbyAlgolia
Submit Docs

Echo Platform Documentation

repository·master·Indexed 19 days ago

https://github.com/merit-systems/echo

Echo is a user-pays AI infrastructure that allows developers to integrate LLMs into applications without fronting API costs. It enables a revenue model where users pay for usage via OAuth-based balances and developers earn markups. The platform includes a Control Plane, Echo Server, and SDKs for React, Next.js, and AI x402 payment integration, supporting providers like OpenAI, Anthropic, and Google.

Tokens
74K
Snippets
306
Records
378
Agent score
66%

What's inside Echo

  1. Overview of available Echo Components

    master

    Echo provides pre-built React components designed for the Echo ecosystem, offering built-in support for authentication, billing, and user management. They are WCAG compliant and follow a unified design system.

    Echo Account Components

    These components handle user-facing account management:

    • Echo Account Button: A complete management interface including balance display, top-up functionality, and user profile access.
    • Echo Account (React): A React implementation featuring integrated hooks.
    • Echo Account (Next.js): An optimized version for Next.js with SSR support.

    UI Components

    General purpose UI elements with Echo-specific enhancements:

    • Echo Button: An enhanced button component with Echo-specific variants.
    • Money Input: A specialized input field for handling and formatting monetary values.
    • Echo Logo: A branded logo component that supports light and dark modes.

  2. Echo SDK Overview

    master

    Echo provides several SDKs depending on your runtime and framework:

    • Echo TS SDK (@merit-systems/echo-typescript-sdk): The core TypeScript SDK that all other framework-specific SDKs are built upon.
    • Echo Next.js SDK (@merit-systems/echo-next-sdk): Optimized for Next.js 15+ App Router integration.
    • Echo React SDK (@merit-systems/echo-react-sdk): Optimized for React client-side Single Page Applications (SPAs).

  4. Choose an Echo integration pattern for existing apps

    master

    If you are adding Echo to an existing application, choose one of the following three integration patterns based on your architecture:

    1. Next.js SDK: Best for Next.js applications. Provides server-side auth with automatic token management.
    2. React SDK: Best for client-side React applications. Uses OAuth2 + PKCE for secure LLM calls from the browser.
    3. TypeScript SDK: Best for backends, CLI tools, or when you need maximum flexibility. Provides direct API access via API keys.

  5. How Echo Works: System Overview & Architecture

    master

    Echo is a proxy layer that sits between your application and LLM providers (like OpenAI or Anthropic) to handle authentication, metering, and billing. It operates as a three-layer stack:

    1. Your Application: Uses an Echo SDK to make LLM calls.
    2. Echo Proxy Layer: Intercepts requests to validate credentials, route to providers, and record usage.
    3. LLM Providers: The final destination for the forwarded requests.

    Core Components

    • Echo Control (packages/app/control): The web dashboard for managing apps, viewing user analytics, and handling billing. It uses a PostgreSQL database and NextAuth.
    • Echo Server (packages/app/server): The API proxy that intercepts requests, validates authentication, meters usage, and routes requests to LLM providers in real-time.
    • SDK Ecosystem:
      • echo-typescript-sdk: Universal client for all platforms.
      • echo-react-sdk: Provides OAuth2+PKCE support for secure client-side (browser) LLM calls.
      • echo-next-sdk: Optimized for server-side integration patterns in Next.js.

  6. Important constraints for Referrals

    master

    When implementing referrals, keep the following business rules in mind:

    • Uniqueness: Referral codes are unique per user, per app.
    • Single Referrer: A user can only have one referrer per app (enforced on a first-come, first-served basis).
    • Beta Status: This feature is in early beta and may exhibit unexpected behavior. Contact the team via Discord for assistance.

  7. Implement authentication with EchoSignIn

    master

    Use the EchoSignIn component to provide a sign-in interface. It handles the complete OAuth2 + PKCE authentication flow:

    1. User clicks the EchoSignIn component.
    2. The OAuth2 + PKCE flow is initiated.
    3. The user is redirected to the Echo authentication server.
    4. Upon successful authentication, the user is redirected back to your app.
    5. The SDK automatically manages token storage and refreshing.

  8. How Echo works: Replacing AI SDK imports

    master

    Echo allows you to offload AI costs to your users. Instead of using a direct provider API key (which requires you to front the costs), you use Echo's model providers. Users authenticate via OAuth, maintain a balance, and pay for their own usage. You can set a markup to earn revenue automatically.

    // Before: Fronting costs yourself with a direct API key
import { openai } from '@ai-sdk/openai';
import { generateText } from 'ai';
const response = await generateText({
  model: openai('gpt-5'),
  'YOUR-API-KEY',
  prompt: '...'
});

// After: Users pay, you earn markup, zero infrastructure
import { useEchoModelProviders } from '@merit-systems/echo-react-sdk';
import { generateText } from 'ai';

const { openai } = useEchoModelProviders();
const response = await generateText({
  model: openai('gpt-5'),
  prompt: '...',
});

  10. Understand the payout lifecycle and processing

    master

    Echo processes claims daily via the Terminal.

    Payout Behavior:

    • Funds are sent to the GitHub user or repository that was configured in your app settings at the exact time of the payout.
    • Critical: If no GitHub account is configured in your app settings when the payout occurs, the transfer for that day will be skipped.
    • If a transfer is skipped, you can manually claim your funds through the Terminal once they have been transferred.

  11. How the Echo Proxy Layer Intercepts Requests

    master

    Echo Server intercepts standard OpenAI-compatible API calls. For example, a call to openai.chat.completions.create is routed through an Echo proxy endpoint (e.g., https://echo.router.merit.systems/v1/chat/completions).

    The proxy preserves the OpenAI API contract, allowing you to use existing code while Echo performs the following internally:

    • Extracts and validates authentication context.
    • Forwards the request to the LLM provider.
    • Calculates costs based on token usage.
    • Records the transaction (user ID, app ID, cost, and tokens) for billing.
    // Your app calls this standard pattern
const response = await openai.chat.completions.create({
  model: "gpt-5",
  messages: [{ role: "user", content: "Hello" }]
});

// Echo intercepts at https://echo.router.merit.systems/v1/chat/completions
// Validates auth, meters usage, forwards to OpenAI, records billing

  12. How the Echo TypeScript SDK architecture works

    master

    The TypeScript SDK is designed around two distinct functional components that can be used independently or together:

    1. Platform Client (EchoClient): Used for managing the Echo account, including billing, apps, and platform-level resources.
    2. AI Providers: Factory functions that generate providers compatible with the Vercel AI SDK, enabling automatic billing for AI model usage.

    This separation allows developers to build server-side applications, CLI tools, or custom integrations that either manage platform state or consume AI services with integrated billing.