> ## Documentation Index > Fetch the complete documentation index at: https://docs.echozero.app/llms.txt > Use this file to discover all available pages before exploring further. # Post a signed trading signal for a developer agent (webhook ingress) > Authenticates via per-agent signing secret (`X-EZ-*` headers). Accepts natural-language `text`, full structured JSON with `eventType` (#1098), or legacy `action`/`tokenAddress`. See `docs/INBOUND_AGENT_WEBHOOK.md`. ## OpenAPI ````yaml https://mcp.echozero.app/api/docs-json post /api/public/agent-signals/{agentId} openapi: 3.0.0 info: title: EchoZero MCP API description: >- EchoZero MCP Server - Developer API for agent management, trading, marketplace, and AI chat. **Rate Limiting:** All endpoints enforce per-API-key rate limits. Tiers: free (60 req/min), standard (300 req/min), premium (1000 req/min). Every response includes `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. Exceeding the limit returns `429 Too Many Requests` with a `Retry-After` header. version: '1.0' contact: {} servers: - url: https://mcp.echozero.app description: Production security: [] tags: - name: MCP Protocol description: >- Model Context Protocol (Streamable HTTP): `/mcp`, `/mcp/sse` — not under `/api`; same API key as REST - name: Health description: Server health check - name: API Keys description: API key generation, listing, and revocation - name: User description: >- User profile, sessions, social, onboarding, internal agent subscriptions, and bot activations (v1: /v1/users/me) - name: Token description: Token data and trending - name: Trade description: Trade execution and history - name: Strategy description: Strategy (trading bot) configuration and control - name: Agent description: Agent registration and management - name: AI description: AI chat, intent, and insights - name: Wallet description: Wallet operations, deposits, and withdrawals - name: Notification description: Notification management and settings - name: Auth description: >- Public authentication: signup / login lookup, code verification, Google OAuth, refresh, and sign-out. Returns `accessToken` / `refreshToken` in the JSON body. - name: OAuth description: >- OAuth 2.1 authorization-code + PKCE for AI assistant clients: `/oauth/authorize`, `/oauth/token`, `/oauth/introspect`, `/status`. - name: Activity description: User trade activity list and search - name: Feed description: Social activity feed timeline - name: Earn description: Leaderboard, rewards, and referrals - name: Statics description: Countries, languages, and static data - name: Misc description: File uploads and utility endpoints - name: Developer description: Developer registration and profile - name: Developer dashboard description: >- Per-agent dashboard: subscribers (anonymized), performance detail, signal history (v1) - name: Developer Agent description: Developer agent listings and management - name: Developer Agents (Marketplace) description: Public browse, search, and subscribe to external developer-listed agents - name: Admin description: Admin-only endpoints for review, approval, and platform management - name: Webhooks description: >- Inbound provider webhooks (no API key). Telegram signal-bot uses `X-Telegram-Bot-Api-Secret-Token` when configured. paths: /api/public/agent-signals/{agentId}: post: tags: - Public — Inbound agent signals summary: Post a signed trading signal for a developer agent (webhook ingress) description: >- Authenticates via per-agent signing secret (`X-EZ-*` headers). Accepts natural-language `text`, full structured JSON with `eventType` (#1098), or legacy `action`/`tokenAddress`. See `docs/INBOUND_AGENT_WEBHOOK.md`. operationId: publicAgentSignalsIngestWebhook parameters: - name: agentId required: true in: path schema: type: string - name: X-EZ-Signature in: header description: >- Lowercase hexadecimal HMAC-SHA256(secret, `${X-EZ-Timestamp}.${canonicalJsonBody}`) required: true schema: type: string example: 7c3bdb3e8f94c2eab5d2c4d4c3c3c3c4c4c9d09e89e4c2eab5d2c4d4f3f2f1ee - name: X-EZ-Timestamp in: header description: >- Unix time in seconds (decimal integer). Compared server-side with ±5 minute skew tolerance. required: true schema: type: string example: '1715000000' - name: x-signature in: header required: false description: >- HMAC-SHA256 signature: HMAC-SHA256(secretKey, timestamp + METHOD + path + body). Optional -- when omitted, HMAC verification is skipped. schema: type: string - name: x-timestamp in: header required: false description: >- Request timestamp in epoch milliseconds. Required when x-signature is provided. Rejected if drift exceeds 5 minutes. schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AgentInboundWebhookBodyDto' examples: minimal: summary: minimal value: text: BUY SOL $500 withIdempotency: summary: with idempotencyKey value: text: BUY SOL $500 TP 200 idempotencyKey: tradingview-alert-2026-05-06-001 structuredJson: summary: legacy structured JSON (buy/sell + mint) value: action: buy tokenAddress: So11111111111111111111111111111111111111112 amount: 500 urgency: medium reasoning: >- Momentum breakout after reclaiming VWAP with strong relative volume. context: source: strategy-engine model: breakout-v3 confidence: 0.82 idempotencyKey: strategy-engine-2026-06-23-001 fullSchemaBuy: summary: full schema — Solana long entry with SL/TP value: version: 1 idempotencyKey: agent-entry-2026-07-01-001 clientTimestamp: '2026-07-07T12:48:45.470Z' eventType: buy chain: solana instrument: tokenAddress: So11111111111111111111111111111111111111112 symbol: SOL amount: 500 side: long tradeType: spot entryPrice: 142 reasoning: Breakout above VWAP with strong relative volume. confidence: 0.85 triggers: slPrice: value: 138 targetType: price tps: - label: TP1 value: 150 targetType: price sizePct: 50 - label: TP2 value: 160 targetType: price sizePct: 30 fullSchemaHyperliquid: summary: full schema — Hyperliquid perp long value: version: 1 idempotencyKey: hl-btc-long-001 eventType: buy chain: hyperliquid instrument: market: BTC symbol: BTC amount: 1000 side: long tradeType: perp leverageX: 5 entryPrice: 68000 reasoning: Trend continuation after reclaim of daily VWAP. confidence: 0.78 triggers: slPrice: value: 66500 targetType: price tps: - value: 70000 targetType: price sizePct: 100 fullSchemaPartialSell: summary: full schema — partial close by positionRef value: version: 1 idempotencyKey: partial-001 eventType: partial_sell chain: solana positionRef: sig_wh_agentId_entry-001 sellSizePct: 50 reasoning: Taking half off at first target — letting runner work. confidence: 0.9 fullSchemaTradeIdea: summary: full schema — non-executing trade idea value: version: 1 idempotencyKey: idea-001 eventType: trade_idea chain: hyperliquid instrument: market: ETH symbol: ETH reasoning: Watching for reclaim of 4h VWAP before entering long. confidence: 0.6 ideaId: idea-eth-vwap-2026-07-01 responses: '200': description: >- Ingress outcome (matched / unmatched / skipped / soft error payload). content: application/json: schema: allOf: - $ref: '#/components/schemas/McpSuccessResponseDto' - properties: data: $ref: '#/components/schemas/AgentInboundWebhookResponseDto' '401': description: Missing or invalid signature / timestamp drift. content: application/json: schema: $ref: '#/components/schemas/McpErrorResponseDto' '404': description: Unknown agent id, agent not webhook mode, or secret not provisioned. content: application/json: schema: $ref: '#/components/schemas/McpErrorResponseDto' components: schemas: AgentInboundWebhookBodyDto: type: object properties: text: type: string description: >- Natural-language signal line. Mutually exclusive with structured JSON fields. example: BUY SOL $500 TP 180 SL 165 minLength: 1 maxLength: 8000 version: type: number description: Schema version (currently 1). default: 1 idempotencyKey: type: string description: Required dedupe key for structured event payloads. maxLength: 128 clientTimestamp: type: string description: ISO timestamp; server rejects stale market signals (>5 min). eventType: type: string enum: - trade_idea - buy - scale_in - sell - partial_sell - amend - breakeven - cancel - position_update - trade_review description: >- Structured event lifecycle type. When set, activates the full JSON schema path. chain: type: string enum: - solana - hyperliquid default: solana instrument: $ref: '#/components/schemas/StructuredSignalInstrumentDto' symbol: type: string description: Display symbol (e.g. SOL, BTC). expiresAt: type: string description: Optional TTL ISO timestamp. side: type: string enum: - long - short default: long tradeType: type: string enum: - spot - perp - virtual default: spot leverageX: type: number description: Perp leverage override. orderType: type: string enum: - market - limit entryPrice: type: number entryZone: $ref: '#/components/schemas/StructuredSignalEntryZoneDto' riskMgmt: type: string enum: - fixed - dynamic triggers: $ref: '#/components/schemas/StructuredSignalTriggersDto' positionRef: type: string description: tradeId or original idempotencyKey for lifecycle events. exitPrice: type: number exitReason: type: string enum: - tp_hit - sl_hit - time_stop - manual - ai_decision pnlPct: type: number sellSizePct: type: number description: Partial close % (partial_sell only). changes: $ref: '#/components/schemas/StructuredSignalAmendChangesDto' ideaId: type: string description: 'trade_idea: optional link id for later entry.' currentPnlPct: type: number description: 'position_update: current unrealized P&L %.' relatedTradeId: type: string description: 'trade_review: related trade signal id.' action: type: string enum: - buy - sell description: Legacy structured action when `eventType` is omitted. tokenAddress: type: string description: Legacy Solana mint (also accepted inside `instrument`). amount: type: number description: USD allocation (scaled server-side per subscriber). urgency: type: string enum: - low - medium - high metadata: type: object reasoning: type: string description: Human-readable rationale; required for full-schema events. maxLength: 4000 context: type: object confidence: type: number minimum: 0 maximum: 1 McpSuccessResponseDto: type: object properties: success: type: boolean example: true data: type: object description: Endpoint-specific payload additionalProperties: true required: - success - data AgentInboundWebhookResponseDto: type: object properties: outcome: type: string enum: - matched - unmatched - skipped - error signalId: type: string status: type: string skipReason: type: string description: When `skipped` or `error`, human/machine-readable detail. executionResult: type: object description: >- Present when execution completes (same vocabulary as WebSocket ingress). required: - outcome McpErrorResponseDto: type: object properties: success: type: boolean example: false error: $ref: '#/components/schemas/McpErrorBodyDto' required: - success - error StructuredSignalInstrumentDto: type: object properties: tokenAddress: type: string description: Solana token mint address. market: type: string description: Hyperliquid market identifier. coin: type: string description: Hyperliquid coin symbol (alias for market). StructuredSignalEntryZoneDto: type: object properties: priceLow: type: number priceHigh: type: number required: - priceLow - priceHigh StructuredSignalTriggersDto: type: object properties: slPrice: $ref: '#/components/schemas/StructuredSignalTriggerLevelDto' tps: type: array items: $ref: '#/components/schemas/StructuredSignalTakeProfitLevelDto' timeStopMins: type: number StructuredSignalAmendChangesDto: type: object properties: slPrice: $ref: '#/components/schemas/StructuredSignalAmendSlChangeDto' tps: type: array items: $ref: '#/components/schemas/StructuredSignalTakeProfitLevelDto' McpErrorBodyDto: type: object properties: code: type: string example: NOT_FOUND message: type: string example: Resource not found required: - code - message StructuredSignalTriggerLevelDto: type: object properties: value: type: number targetType: type: string enum: - price - pct trailing: type: boolean required: - value - targetType StructuredSignalTakeProfitLevelDto: type: object properties: label: type: string value: type: number targetType: type: string enum: - price - pct sizePct: type: number description: Partial close % at this TP; sum ≤ 100. required: - value - targetType StructuredSignalAmendSlChangeDto: type: object properties: from: type: number to: type: number ````