Choose your path
Step 0: Get your API key and set up signing
- Sign in at devportal.echozero.app
- Register as a developer
- Create an API key
- Copy
ez_live_...andezs_...(the secret is shown once)
x-api-key, x-timestamp (epoch milliseconds) and x-signature (HMAC-SHA256 of timestamp + METHOD + path + body, signed with your ezs_ secret). Sending only x-api-key returns 401. Paste this helper into your shell once and use it for every call below:
curl, openssl and python3, which come with macOS and most Linux systems. See API keys and HMAC for how the signature is built, and the SDKs if you would rather not sign by hand.
Step 1: Verify the API
The health check is public and needs no key:S in Status.
Step 2: Authenticate
You are authenticated when
success is true and data.id is present.Step 3: Create a webhook agent (optional)
Agent create calls (
POST /api/v1/agents) carry an x-ez-mcp-client header with a short label for your client. The ez helper sends it for you (set EZ_CLIENT to change the label). The API spec lists it as required on this route. Whether the server enforces it is not confirmed, so include it.agentVenueisJUPITER(Solana spot) orHYPERLIQUID(perpetuals). It is set at creation and cannot be changed later. To use the other venue, create a new agent. For a Hyperliquid agent, also include"signalExecutionDefaults": { "marketType": "perpetual" }in the same body. The spec says the server derives the market type from the venue, but older builds rejected Hyperliquid creates without it with a bare 400, so include it. See the Hyperliquid recipe.nameis 20 characters at most.
inboundWebhookSigningSecretReveal (ezw_...) from the response. It is shown once.
A new agent is private. It is only listed on the marketplace after you send isPublic: true and staff approve it. See Agent lifecycle.
Step 4: Send a test signal
Inbound signals use a different signature from REST calls: the per-agentezw_ secret, a timestamp in seconds, and the body written as canonical JSON (keys sorted alphabetically, compact). jq -S -c does that for you. This helper signs and sends in one step:
Write numbers in plain form (
100, 100.5), not 1.0, 100.50 or 1E+3. jq keeps numbers as typed, but the server re-serialises them the JavaScript way, so the signature would not match. Send only documented fields too: the server drops unknown top-level fields before it verifies the signature, and jq would sign them. If you need arbitrary numbers, use an SDK.{"idempotencyKey":"quickstart-001","text":"BUY SOL $50"}, with idempotencyKey before text. If you sign the keys in any other order the server rejects the signature.
Use virtual wallet mode so test signals use simulated balances.
Success:
Known issue: a brand-new private webhook agent can currently return 404 instead of
outcome: matched, because the signal endpoint does not find private agents yet. This is being fixed. If you see a 404 and the agentId in the URL is correct, that is the likely cause, not a signing mistake. The sandbox endpoints work in the meantime.outcome: skipped, read skipReason. See Error codes.
Step 5: Explore further
API conventions
Response envelopes, pagination and rate limits. Then open the API Reference tab for every endpoint and a try-it console.
OpenAPI JSON
Download the machine-readable spec.
Signal envelope
Event types and structured payloads.
Webhook security
HMAC signing and replay protection.
Assistant setup
Theez CLI (@echozero/ez on npm) signs you in with OAuth and wires up your assistant:
EchoZeroApp/skills) is not public yet. Until it is, use the CLI, OAuth or an API key.