Skip to main content

Authentication

Elfa supports two access models:

  1. API key auth for /v2/* and /v2/auto/*
  2. x402 keyless payments for /x402/v2/*

API Key Auth (/v2/* and /v2/auto/*)​

Get your API key from the Elfa Developer Portal.

Include your key in every request:

x-elfa-api-key: your_api_key_here

Example (cURL)​

curl -X GET "https://api.elfa.ai/v2/aggregations/trending-tokens" \
  -H "x-elfa-api-key: your_api_key_here"

Auto API Extra Requirement (/v2/auto/* mutations)​

For mutation endpoints under /v2/auto/*, include HMAC headers in addition to x-elfa-api-key:

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

Signature payload format:

timestamp + method + path + body
  • timestamp: Unix timestamp in seconds
  • method: uppercase HTTP method (POST, DELETE)
  • path: route path used for signature verification (for current Auto implementation, this is the path inside /v2/auto, e.g. /queries, /queries/:id, /chat)
  • body: exact JSON string sent in the request body, or empty string for no body

Replay protection: timestamp drift must be within 30 seconds.

Concrete signing example (including mounted-path behavior): /auto/overview

Full /v2/auto docs: /auto/overview

x402-specific Auto differences: /auto/x402

x402 Keyless Auth (/x402/v2/*)​

x402 routes do not require API keys. They use per-request USDC payment headers:

  • PAYMENT-SIGNATURE (preferred)
  • X-PAYMENT (legacy)

Details: x402 Payments

Troubleshooting​

  1. 401 Unauthorized: missing/invalid API key, missing HMAC headers, invalid signature, or timestamp drift
  2. 403 Forbidden: API key lacks permission or Auto is not enabled/linked for /v2/auto
  3. 402 Payment Required: x402 payment header missing/invalid for /x402/v2/*
  4. 429 Too Many Requests: rate limit exceeded