Skip to main content
POST
/
api
/
public
/
agent-signals
/
{agentId}
curl --request POST \ --url https://mcp.echozero.app/api/public/agent-signals/{agentId} \ --header 'Content-Type: application/json' \ --header 'X-EZ-Signature: <x-ez-signature>' \ --header 'X-EZ-Timestamp: <x-ez-timestamp>' \ --data '{}'
{
  "success": true,
  "data": {
    "signalId": "<string>",
    "status": "<string>",
    "skipReason": "<string>",
    "executionResult": {}
  }
}

Headers

​
X-EZ-Signature
string
required

Lowercase hexadecimal HMAC-SHA256(secret, ${X-EZ-Timestamp}.${canonicalJsonBody})

Example:

"7c3bdb3e8f94c2eab5d2c4d4c3c3c3c4c4c9d09e89e4c2eab5d2c4d4f3f2f1ee"

​
X-EZ-Timestamp
string
required

Unix time in seconds (decimal integer). Compared server-side with ±5 minute skew tolerance.

Example:

"1715000000"

​
x-signature
string

HMAC-SHA256 signature: HMAC-SHA256(secretKey, timestamp + METHOD + path + body). Optional -- when omitted, HMAC verification is skipped.

​
x-timestamp
string

Request timestamp in epoch milliseconds. Required when x-signature is provided. Rejected if drift exceeds 5 minutes.

Path Parameters

​
agentId
string
required

Body

application/json
​
text
string

Natural-language signal line. Mutually exclusive with structured JSON fields.

Required string length: 1 - 8000
Example:

"BUY SOL $500 TP 180 SL 165"

​
version
number
default:1

Schema version (currently 1).

​
idempotencyKey
string

Required dedupe key for structured event payloads.

Maximum string length: 128
​
clientTimestamp
string

ISO timestamp; server rejects stale market signals (>5 min).

​
eventType
enum<string>

Structured event lifecycle type. When set, activates the full JSON schema path.

Available options:
trade_idea,
buy,
scale_in,
sell,
partial_sell,
amend,
breakeven,
cancel,
position_update,
trade_review
​
chain
enum<string>
default:solana
Available options:
solana,
hyperliquid
​
instrument
object
​
symbol
string

Display symbol (e.g. SOL, BTC).

​
expiresAt
string

Optional TTL ISO timestamp.

​
side
enum<string>
default:long
Available options:
long,
short
​
tradeType
enum<string>
default:spot
Available options:
spot,
perp,
virtual
​
leverageX
number

Perp leverage override.

​
orderType
enum<string>
Available options:
market,
limit
​
entryPrice
number
​
entryZone
object
​
riskMgmt
enum<string>
Available options:
fixed,
dynamic
​
triggers
object
​
positionRef
string

tradeId or original idempotencyKey for lifecycle events.

​
exitPrice
number
​
exitReason
enum<string>
Available options:
tp_hit,
sl_hit,
time_stop,
manual,
ai_decision
​
pnlPct
number
​
sellSizePct
number

Partial close % (partial_sell only).

​
changes
object
​
ideaId
string

trade_idea: optional link id for later entry.

​
currentPnlPct
number

position_update: current unrealized P&L %.

​
relatedTradeId
string

trade_review: related trade signal id.

​
action
enum<string>

Legacy structured action when eventType is omitted.

Available options:
buy,
sell
​
tokenAddress
string

Legacy Solana mint (also accepted inside instrument).

​
amount
number

USD allocation (scaled server-side per subscriber).

​
urgency
enum<string>
Available options:
low,
medium,
high
​
metadata
object
​
reasoning
string

Human-readable rationale; required for full-schema events.

Maximum string length: 4000
​
context
object
​
confidence
number
Required range: 0 <= x <= 1

Response

Ingress outcome (matched / unmatched / skipped / soft error payload).

​
success
boolean
required
Example:

true

​
data
object
required

Endpoint-specific payload