Skip to main content
Get from zero to a signed API call and an optional test signal. Every API-key call is signed, so this page sets up a small helper first. For the full end-to-end path, start with Build your first agent.

Choose your path

Step 0: Get your API key and set up signing

  1. Sign in at devportal.echozero.app
  2. Register as a developer
  3. Create an API key
  4. Copy ez_live_... and ezs_... (the secret is shown once)
REST calls made with an API key need three headers: 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:
It needs 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:
Note the capital S in Status.

Step 2: Authenticate

Expected:
You are authenticated when success is true and data.id is present.
Getting 401? Check that all three headers are sent and that your clock is within 5 minutes. See Error codes.

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.
Two fields to get right the first time:
  • agentVenue is JUPITER (Solana spot) or HYPERLIQUID (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.
  • name is 20 characters at most.
Expected (abbreviated):
Save 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-agent ezw_ 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.
The signed text for that body is {"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.
If you get 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

The ez CLI (@echozero/ez on npm) signs you in with OAuth and wires up your assistant:
The skills pack (EchoZeroApp/skills) is not public yet. Until it is, use the CLI, OAuth or an API key.