Skip to main content
Portal

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
Credential Hygiene: Never Print Env Vars

Never print or log ELFA_API_KEY or full auth headers.

Avoid debug patterns like echo $ELFA_API_KEY, printenv, or console.log(process.env).

If you need diagnostics, log only redacted metadata (for example endpoint and timestamp), not secret values.

Example (cURL)​

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

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

Auto uses the same x-elfa-api-key header. There is no separate portal enablement step; a new API key can call /v2/auto/* immediately.

Use Auto API Key Auth for the Auto-specific route list and create example.

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

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

  • PAYMENT-SIGNATURE — carries the signed payment

These routes speak x402 v2 only. X-PAYMENT is accepted as an alias for the header name, but the payload must be v2 — a v1 client reads its quote from the 402 body, which is empty, and finds nothing to sign.

Details: x402 Payments

Troubleshooting​

  1. 401 Unauthorized: missing or invalid API key
  2. 403 Forbidden: API key lacks permission or the user cannot perform the requested Auto operation
  3. 402 Payment Required: x402 payment header missing/invalid for /x402/v2/*
  4. 429 Too Many Requests: rate limit exceeded