Lucid Agents

The Lucid documentation is organized into several functional families that guide users through the lifecycle of using the platform:

• Home: High-level positioning and stack boundaries.
• Start: Quickstart paths for sellers, buyers, existing apps, and coding agents.
• Build: Implementation details for capabilities, payment models, tasks, and storefronts.
• Buy: Guidance on paid calls, discovery, budgets, and wallet interoperability.
• Operate: Production concerns including durable state, observability, security, and deployment runbooks.
• Protocols: Technical specifications for x402, MPP, SIWX, A2A, ERC-8004, and AP2.
• Packages: Reference for @lucid-agents core, extensions, adapters, and CLI.
• Examples: A gallery of runnable patterns (A2A, MPP, Scheduler, etc.).
• Products: Information on hosted platforms, routers, and agent creation.
• Migration guides: Instructions for moving between runtimes (v3) and protocol versions (x402 v2).
• Reference: Technical details on configuration, environment variables, errors, and telemetry.

The packages/examples/ directory contains various specialized examples. Use these as templates for your own implementation:

The following table summarizes the current completeness of the Lucid documentation across major functional areas. Use this to identify which sections may require more depth or verification before production use:

Lucid provides a multi-protocol payment surface covering EVM (Ethereum Virtual Machine), Solana, Tempo, Stripe, and Lightning networks.

Key Concepts:

• Built in: Lucid registers and coordinates the implementation. However, you still need to provide credentials, accounts, network access, and provider configuration.
• Exact vs. Upto (x402):
  • exact schemes require the handler to return the specific amount requested.
  • upto schemes allow a ceiling; the handler must return a non-negative payment.actualAmount that is $\le$ the accepted ceiling.
• Durability: By default, payment-policy accounting and challenge replay fences use process-local memory (intended for development). For production, you should use the provided SQLite or Postgres durable adapters to ensure state survives restarts.
• Facilitator: For many x402 protocols, a facilitator is required for verification and settlement. For upto schemes, the /supported endpoint must include the facilitatorAddress.

Lucid is designed to act as the paid application boundary. When integrating, you should keep model loops, memory, planning, evaluation, and tool selection within your existing agent framework.

There are three primary integration patterns:

1. Agent Frameworks: You can either expose work performed by your framework through Lucid, or call a paid Lucid service as a tool within your framework.
2. MCP (Model Context Protocol): You can use the current HTTP-tool wrapper to interact with MCP, though note there is currently a native MCP gap.
3. Framework Adapters: You can bind the canonical Lucid service runtime to web frameworks like Hono, Express, Next.js, or TanStack Start.

Note on Compatibility: As of the current version, there are no official Lucid adapter packages for OpenAI Agents SDK, Vercel AI SDK, Mastra, LangGraph, AgentKit, or MCP. Integration with these is handled via the supported HTTP composition seam.

Lucid uses an extension architecture to compose a complete commerce runtime by layering different protocols. Developers should understand how these layers interact:

1. Agent Discovery and Collaboration (A2A Layer): Handles agent advertising and defines interactions like messages, artifacts, tasks, streaming, and push notifications.
2. Onchain Identity and Trust (ERC-8004 Layer): Handles identity registration and provides optional reputation or validation signals.
3. Payment Negotiation and Execution (x402 & MPP Layer): Manages the challenge/payment transport, schemes, networks, and assets. Lucid-specific features like budgets, policies, and reservations are considered 'Lucid behavior' rather than core protocol features.
4. Commerce Authorization and Evidence (AP2 Layer): Provides role metadata for commerce flows.

Mental Model: No single protocol provides the full commerce runtime. Lucid acts as the orchestrator that integrates these specialized layers.

To effectively observe commercial operations that span multiple HTTP attempts and systems, you should create one trace or business record per logical operation. This allows you to correlate challenges, denials, charges, and fulfillment states.

Key fields to carry in your trace:

• operation_id: A stable ID across unpaid, paid, and transport retries.
• idempotency_key_ref: A hash or internal reference (do not expose raw sensitive keys).
• attempt_id: A new ID for each network attempt.
• trace_id / span_id: Preserve these through x402 protocol retries.
• run_id: Returned in result/SSE envelopes.
• task_id: Persist in a protected store with the secret access token.
• settlement_ref: A sanitized transaction or receipt reference from the provider/chain.
• accounting_settlement_id: Internal staged/committed accounting batch ID.

Warning: Do not use a wallet address alone as a trace identifier, as it can be sensitive personal data and a single wallet may perform many operations.

/* Recommended field mapping for correlation */
{
  "operation_id": "stable_id",
  "idempotency_key_ref": "hash_ref",
  "attempt_id": "network_attempt_id",
  "trace_id": "otel_trace_id",
  "run_id": "lucid_run_id",
  "task_id": "lucid_task_id",
  "settlement_ref": "sanitized_provider_ref"
}

Lucid uses a typed extension graph for configuration. Instead of a single global configuration object, each extension package owns its own configuration, runtime state, validation, and lifecycle. This ensures that concerns like payments, wallets, or HTTP routing are encapsulated within their respective packages.

Ownership Map