Skip to main content

Agent Quickstart

This guide is the fastest deterministic path for agents to run Auto end-to-end.

Use this with:

Required Sequence (Enforced)

For API key lifecycle calls, use this order exactly:

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

If actions include market_order or limit_order, preflight GET /v2/auto/exchanges before create.

Intent Routing (Strict)​

IntentRoute toMinimum payload contract
Account-anchored post intentsource: "tweet"args.username (no @), args.text, args.minConfidence: 80
World event intentsource: "news"args.text, args.minConfidence: 80
Fuzzy world-state predicate (not naturally tweet/news)source: "llm"method: "athena_condition", args.query, args.period >= "1h"

1) Pick Access Mode​

ModeRoute PrefixPrimary Auth
API key/v2/auto/*x-elfa-api-key (+ HMAC on trade-action mutations and exchange linking; notification-only mutations skip HMAC)
x402/x402/v2/auto/*x402 payment header (+ x-elfa-agent-secret on query lifecycle routes)

2) Load Endpoint Metadata (Machine-Readable)​

Manifest URL:

/agent/endpoints.manifest.json

Each entry provides:

  • method/path
  • docs route
  • required headers
  • HMAC requirement and mounted signature path template
  • payment requirement
  • request and response examples

API key mode (/v2/auto/*)​

  1. If query uses market_order or limit_order, verify readiness first: GET /exchanges (and connect if needed via portal flow or POST /exchanges).
  2. POST /chat
  3. POST /queries/validate
  4. POST /queries
  5. GET /queries/{queryId}/stream (or GET /queries/{queryId} polling)
  6. GET /queries/{queryId}/sessions and GET /queries/{queryId}/sessions/{sessionId} when using llm action

x402 mode (/x402/v2/auto/*)​

  1. POST /chat
  2. POST /queries/validate
  3. POST /queries
  4. GET /queries/{queryId}/stream (or POST /queries/{queryId} polling)
  5. POST /queries/{queryId}/sessions and POST /queries/{queryId}/sessions/{sessionId} when using llm action

4) Auth Rules You Must Enforce​

API key mode​

  • Always send x-elfa-api-key.
  • On mutation routes, also send x-elfa-timestamp and x-elfa-signature.
  • Sign payload as:
timestamp + method + mounted_path + body

Mounted path example:

  • request URL: /v2/auto/queries
  • signed path: /queries

x402 mode​

  • Send payment header (PAYMENT-SIGNATURE preferred; X-PAYMENT legacy).
  • Persist one stable x-elfa-agent-secret per agent identity.
  • Do not rotate agent secret per request/session.

5) Runtime Pattern (Production)​

  1. Validate before create.
  2. For trade actions, preflight GET /exchanges and require active connection before create.
  3. Prefer webhook/SSE for real-time delivery.
  4. Deduplicate by event ID.
  5. Hand off to a background runner for policy and execution.

Execution Monitoring (Trade Actions)​

  • Poll GET /queries/{queryId} to inspect the latest executions array and error payloads.
  • Use GET /executions (or GET /executions/{executionId}) for execution-centric views and debugging.
  • Treat failed execution entries as actionable operational events (credentials, balances, exchange readiness, policy guards).

For implementation details:

6) Failure Handling Order​

  1. Retry transient network errors with backoff.
  2. On validation failure (400/422), repair query and re-validate.
  3. On auth failures (401/403), refresh credentials or enablement state.
  4. On x402 payment failure (402), re-price and retry with valid payment payload.