Skip to main content

Create Query

POST 
/v2/auto/queries

Create and activate a conditional query.

Required Sequence (Enforced)​

Call POST /v2/auto/queries/validate immediately before create.

For trade actions (market_order, limit_order), preflight GET /v2/auto/exchanges before create.

Lifecycle after create:

  1. POST /v2/auto/queries/{queryId}/cancel while status is active.
  2. DELETE /v2/auto/queries/{queryId} only when status is terminal (triggered, expired, cancelled, failed).

Allowed action types (API key mode): webhook, notify, telegram_bot, llm, market_order, limit_order.

Trade actions (market_order, limit_order) require an active exchange connection for the linked user (for example Hyperliquid via POST /v2/auto/exchanges). Without a connected exchange, query creation can succeed but order execution fails when the trigger fires.

Cost​

Simulation-driven estimate (reference values):

  • baseline: 5 credits ($0.045)
  • fast call: +5 credits (+$0.045)
  • expert call: +18 credits (+$0.162)

Auth​

Required header (always):

x-elfa-api-key: <api_key>

HMAC is conditional — required when the request body's action is trade-flavoured (market_order, limit_order, or llm whose params.callback.action.type is market_order or limit_order). HMAC is NOT required for notification-only actions (notify, telegram_bot, webhook, or llm with a notification callback). Unknown action types default to requiring HMAC.

When HMAC is required, also send:

x-elfa-timestamp: <unix_seconds>
x-elfa-signature: <hex_hmac_sha256>

Signing payload: timestamp + method + path + body. For this route, sign with path = "/queries". Always-signing clients are supported — HMAC sent on a notification-only request is accepted.

Request Example​

{
  "query": {
    "conditions": {
      "AND": [
        {
          "source": "price",
          "method": "current",
          "args": { "symbol": "BTC" },
          "operator": ">",
          "value": 100000
        }
      ]
    },
    "actions": [
      {
        "stepId": "step_1",
        "type": "notify",
        "params": { "message": "BTC crossed target" }
      }
    ],
    "expiresIn": "24h"
  },
  "title": "BTC breakout alert",
  "description": "Notify when BTC is above 100k"
}

Response Example (201)​

{
  "queryId": "a12d20ff-6cb2-433e-afed-cc2e6a0380b6",
  "status": "active",
  "estimatedCredits": 116,
  "simulationLlmCallsEstimate": {
    "conditionCallsUpperBound": 1,
    "actionCallsUpperBound": 0,
    "conditionCallsBySpeed": {"fast": 1, "expert": 0, "adaptive": 0},
    "actionCallsBySpeed": {"fast": 0, "expert": 0, "adaptive": 0}
  }
}

Best practice: call validate first, then create. After creation, wire notifications (webhook, telegram_bot, or SSE) to a background runner.

Request​

Responses​

Ok