Skip to main content
Get API Key

x402 (Auto)

Use this page for keyless, pay-per-request Auto access on /x402/v2/auto/*. If you still need to choose between API key and x402 models, start with Auto Overview.

Base URL​

https://api.elfa.ai/x402/v2/auto

Required Auth and Identity​

x402 mode does not use API keys. Use the x402 payment header on requests:

  • PAYMENT-SIGNATURE — carries the signed payment

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. See x402 Payments.

Supported Actions

x402 Auto supports webhook, notify, telegram_bot, and llm actions only.

Auto query routes in x402 use a secret-based identity via header:

  • include x-elfa-agent-secret on validate, create, poll, cancel, list sessions, get session, and stream routes

Agent Secret Management (Generate Once, Reuse Always)​

For x402 Auto, your secret is the agent identity for query/session ownership.

Generate a strong secret once when your agent is initialized:

openssl rand -hex 32

or

node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"

Then persist it in long-term storage (secret manager, encrypted env config, or agent memory store) and reuse the same value for all query lifecycle calls.

Recommended pattern:

  1. Generate once at onboarding.
  2. Save as ELFA_AGENT_SECRET (or equivalent).
  3. Reuse the same secret for create, poll, cancel, sessions, and stream calls.
  4. Do not regenerate per request or per session.

Why this matters:

  • x402 session ownership is derived from SHA256(secret).
  • If you change secrets, your agent identity changes.
  • Existing query/session access may fail or appear missing under the new identity.
Agent Secret vs Webhook Signing Secret

x-elfa-agent-secret identifies the agent for query/session ownership. For webhook delivery verification, prefer an explicit webhook.params.signingSecret on each webhook action instead of relying on the legacy agent-secret-derived webhook signature fallback.

Pricing (Auto x402)​

Builder chat (POST /x402/v2/auto/chat)​

Pay a flat price with exact, or, on Base when the 402 lists it, pay from a prepaid batch-settlement channel and be charged only what the turn actually used, up to the cap. See payment schemes.

Speedexact (flat)batch-settlement (charged up to)
fast$1$2
expert (default)$2$6

Query creation (POST /x402/v2/auto/queries)​

  • baseline: 5 credits ($0.0725)
  • per fast LLM call: +5 credits (+$0.0725)
  • per expert LLM call: +18 credits (+$0.261)

These credits price query creation only. Builder chat is quoted in USD per turn — see the table above.

Endpoint Reference​

For Auto x402 endpoint details, use the API reference pages:

Stream notifications is per-query only on x402. The account-wide stream available on /v2/auto (GET /v2/auto/queries/stream) is deliberately not exposed here: an x402 agent's identity is self-asserted, and the per-query stream tolerates that only because a caller must also know the query's UUID. See Notifications.

When to Choose x402​

Use x402 Auto when you want:

  • keyless integration (wallet-based access)
  • request-by-request billing in USDC
  • agent flows without API key provisioning