Authentication

Elfa supports two access models:

Routes	Auth
/v3/*	API key, x-elfa-api-key header. Access depends on the plan
/v2/* and /v2/auto/*	API key, x-elfa-api-key header
/x402/v2/*	No key. A per-request USDC payment header

API Key

1. 1
   Visit the Elfa Developer Portal

   Get your Elfa API key

   Sign up or log in, then open the API Key tab. Keep the key secret; never share it publicly.

2. 2
   Set the key as an environment variable

   Shell

   export ELFA_API_KEY="your_api_key_here"
3. 3
   Send it in the x-elfa-api-key header

   Every request needs the header. With the variable set, your first call looks like this:

   curl "https://api.elfa.ai/v2/aggregations/trending-tokens" \
     -H "x-elfa-api-key: $ELFA_API_KEY"

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.

API v3 (/v3/*)

Send x-elfa-api-key: <your key> on every request. A 401 says why it failed:

message	Fix
API key is required	Send the header
Invalid or expired API key	Check the key. A mistyped or revoked key gets this
Error validating API key	Our side. Retry

A 503 ERR_SERVICE_UNAVAILABLE means the key could not be checked just then, or, with q, that search is down. It says nothing about the key. Retry after a few seconds.

Access

PAYG, Grow and Enterprise keys can call every v3 endpoint. A Free key can call only /v3/key-status. Get a key, or upgrade, in the Developer Portal. Each 403 names its next step:

403 reads	When	Do
The v3 API is free on the Pay-as-you-go and Grow plans. Upgrade at …	A Free key, on any endpoint but /v3/key-status	Upgrade in the Developer Portal
API key does not have the required scope: …	A paid key without this endpoint	Email [email protected] with the requestId

/v3/key-status lists the scopes your key holds.

API v2 (/v2/*)

/v2/* uses the same x-elfa-api-key header. See the API v2 overview for the endpoints.

Auto (/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. On v3, see Access
3. 402 Payment Required: x402 payment header missing/invalid for /x402/v2/*
4. 429 Too Many Requests: rate limit exceeded. See Rate Limits

See Errors for the error bodies.