# EchoZero

> EchoZero is an AI-native trading platform where users can discover, build, subscribe to, and operate trading agents. The platform combines agent profiles, strategy execution, wallet operations, marketplace signals, analytics, and chat workflows behind developer-friendly REST and MCP interfaces so AI assistants can inspect platform state and take authorized actions for users and developers.

## Primary URLs

- Website: https://echozero.app/
- Developer portal: https://devportal.echozero.app/
- Developer docs: https://docs.echozero.app/
- REST API base: https://mcp.echozero.app/api
- OpenAPI spec: https://mcp.echozero.app/api/docs-json
- MCP server: https://mcp.echozero.app/mcp
- MCP SSE stream: https://mcp.echozero.app/mcp/sse
- GitHub skills repo: https://github.com/EchoZeroApp/skills-draft
- GitHub SDK repo: https://github.com/EchoZeroApp/echozero-sdk
- GitHub docs repo: https://github.com/EchoZeroApp/echozero-docs
- MCP directory metadata: https://mcp.echozero.app/public/index.json
- ChatGPT App Directory manifest: https://mcp.echozero.app/public/directory/chatgpt/ai-plugin.json
- Claude Connector metadata: https://mcp.echozero.app/public/directory/claude/connector.json
- Gemini Extension metadata: https://mcp.echozero.app/public/directory/gemini/extension.json
- OpenClaw ClawHub listing: https://mcp.echozero.app/public/directory/openclaw/listing.json
- Smithery listing metadata: https://mcp.echozero.app/public/directory/smithery/listing.json
- Glama listing metadata: https://mcp.echozero.app/public/directory/glama/listing.json

## Authentication

Developer API access uses OAuth 2.1 authorization code + PKCE or an API key. OAuth endpoints:

- Authorize: https://mcp.echozero.app/oauth/authorize
- Token: https://mcp.echozero.app/oauth/token
- Introspect: https://mcp.echozero.app/oauth/introspect
- Verify status: https://mcp.echozero.app/status

For API-key access, send the key on REST and MCP requests with either:

- `x-api-key: <developer_api_key>`
- `Authorization: Bearer <developer_api_key>`

MCP Streamable HTTP sessions require the same API key on every request, including `initialize`. After initialization, send the returned `mcp-session-id` header on subsequent `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, `prompts/get`, `/mcp/sse`, and session-delete requests.

## MCP Protocol

- `POST https://mcp.echozero.app/mcp` — JSON-RPC 2.0 for `initialize`, `tools/list`, `tools/call`, `resources/list`, `resources/read`, `prompts/list`, and `prompts/get`.
- `GET https://mcp.echozero.app/mcp/sse` — server-sent event stream for an initialized MCP session.
- `DELETE https://mcp.echozero.app/mcp` — end an initialized MCP session.

Available MCP tools, resources, and prompts are scope-gated by the API key. Common scopes include `read:agents`, `write:agents`, `read:wallet`, `write:wallet`, `read:strategies`, `write:strategies`, `read:trades`, `read:tokens`, `write:ai`, and `admin:*`.

## Key REST Endpoints

All paths below are relative to `https://mcp.echozero.app/api`.

### Agents

- `GET /v1/agents` — list owned agents.
- `POST /v1/agents` — create an agent.
- `GET /v1/agents/{id}` — get an owned agent.
- `PATCH /v1/agents/{id}` — update an owned agent.
- `DELETE /v1/agents/{id}` — delete an owned agent.
- `POST /v1/agents/{id}/avatar` — upload an agent avatar.
- `GET /v1/agents/explore` — browse/explore agents.
- `GET /v1/agents/pinned` — list pinned agents.
- `POST /v1/agents/{id}/pin` — pin an agent.
- `DELETE /v1/agents/{id}/pin` — unpin an agent.

### Signals

- `GET /developers/signals` — list trade signals for the authenticated developer.
- `GET /developers/signals/{signalId}` — get a developer-owned trade signal.
- `GET /developers/signals/agent/{agentId}` — list trade signals for a developer agent.
- `POST /public/agent-signals/{agentId}` — post a signed trading signal for a webhook-enabled developer agent.
- `GET /v1/developers/agents/{id}/signals/ingest-log` — inspect signal ingestion history for a developer agent.
- `GET /v1/developers/agents/{id}/trades` — list signal-trade rows for a developer agent.

### Wallet

- `GET /v1/wallet/mode` — get wallet mode.
- `POST /v1/wallet/mode` — toggle wallet mode.
- `GET /v1/wallet/chart` — get historical wallet chart data.
- `GET /v1/wallet/trades/search` — search wallet trades.
- `POST /v1/wallet/deposit` — deposit funds.
- `POST /v1/wallet/withdraw` — withdraw funds.
- `POST /v1/wallet/buy` — buy tokens.
- `POST /v1/wallet/sell` — sell tokens.
- `POST /v1/wallet/virtual/add-funds` — add virtual wallet funds.

### Stats

- `GET /v1/strategies/status-counts` — get strategy status/category counts.
- `GET /v1/strategies/{id}/performance` — get strategy performance.
- `GET /v1/developers/agents/{id}/performance` — get developer-agent performance stats.
- `GET /v1/developers/agents/{id}/subscribers` — get anonymized subscriber and fee stats.
- `GET /v1/notifications/counts` — get notification counts by type.

## Additional Context

- Public marketplace agents: `GET /v1/developer-agents`
- Current user: `GET /v1/users/me`
- Token data: `GET /v1/tokens`
- AI chat and actions: `POST /v1/ai/chat`, `POST /v1/ai/agents/{agentId}/chat`, and related `/v1/ai/*` routes.
- Integration guides (signals, webhooks, sandbox): https://docs.echozero.app/