Inbound endpoint
For webhook-based agents (signalSourceKind: webhook):
Payload modes
Three modes are supported. They are mutually exclusive - send one style per request.Event types
Envelope fields (full schema)
Entry fields (buy, scale_in)
Lifecycle fields (sell, partial_sell, amend, breakeven, cancel)
Feed-only fields (position_update, trade_review)
Legacy structured fields
Used wheneventType is omitted (together with action and tokenAddress):
Examples
Natural language
Entry - structured buy
Scale in
Sell (full exit)
Amend SL/TP
Breakeven
Cancel
Perp with leverage
Perpetual signals need an agent created withagentVenue: "HYPERLIQUID". The venue cannot be changed after creation. See the Hyperliquid recipe.
Lifecycle - partial sell
Feed-only - trade idea
Feed-only - position update
Feed-only - trade review
Legacy structured
Idempotency
- Full schema:
idempotencyKeyis required wheneventTypeis set. - Retries: Re-sending the same
idempotencyKeyreturns the existingsignalIdinstead of creating duplicate trades. - Lifecycle: Use the entry’s
idempotencyKey(or its trade id) aspositionReffor exits and amendments. For atrade_review,relatedTradeIdalso accepts the returnedsignalId.
my-bot-2026-07-06-entry-001.
Signal ids returned by this endpoint look like sig_wh_<agentId>_<idempotencyKey>.
Response
Standard MCP envelope. Typicaldata fields:
Soft failures return HTTP 200.
unmatched, failed, skipped and error are reported in the body, so check outcome, not only the status code.
Signing secret lifecycle
- Provision: Creating an agent with
signalSourceKind: webhookreturnsinboundWebhookSigningSecretRevealonce (ezw_...). - Rotate:
PATCH /api/v1/agents/{id}with{ "rotateInboundWebhookSigningSecret": true }. - Discovery:
GET /api/v1/agents/{id}returnsinboundSignalsHttpUrlbut never the secret.
Other transports
Outbound execution callbacks
When you setwebhookUrl on an agent, EchoZero POSTs signal.execution events to your server after trade attempts. This is separate from inbound signing - see Webhook security.