Lucid Agents Docs

Requirements

Bun 1.3 or Node.js 20.9 or newer
TypeScript 5.9 and Zod 4 for TypeScript projects
A receiving address to sell paid services
A signing wallet with testnet USDC to buy paid services

Recommended: scaffold a service

bunx @lucid-agents/cli@2.5.0 my-service --adapter=hono
cd my-service
bun install

Pinning the CLI makes the generated code and this Stable guide reproducible. The Stable blank template may need the domain extensions used by your service:

bun add \
  @lucid-agents/core@2.5.0 \
  @lucid-agents/http@1.10.2 \
  @lucid-agents/payments@2.5.0 \
  @lucid-agents/hono@0.9.6 \
  @x402/core@2.19.0 \
  @x402/evm@2.19.0 \
  @x402/fetch@2.19.0 \
  viem@2.44.4 \
  zod@^4.1.12

There is no dedicated Lucid package for Next.js. It is an adapter generated by the CLI:

bunx @lucid-agents/cli@2.5.0 my-service --adapter=next

Do not install old unscoped x402 packages. The scoped x402 packages above are direct dependencies because the Stable buyer example imports their public v2 registration API. This avoids relying on a transitive dependency or on the 2.5.0 Lucid buyer helper, which predates the current v2 registration contract.

Environment variables

Use the prefixed names for new applications:

PAYMENTS_FACILITATOR_URL=https://x402.org/facilitator
PAYMENTS_NETWORK=eip155:84532
PAYMENTS_RECEIVABLE_ADDRESS=0xYOUR_EVM_RECEIVING_ADDRESS

PAYMENTS_FACILITATOR_URL above is the signup-free x402.org testnet-only facilitator. Use a production facilitator and mainnet address before charging real funds. A capability price such as "0.01" means $0.01 USDC, not atomic token units.

Work on Next

Clone the repository when you need a page marked Next:

git clone https://github.com/daydreamsai/lucid-agents.git
cd lucid-agents
bun install --frozen-lockfile
bun run build:packages

Workspace packages are not a substitute for a Stable release. Do not copy Next-only imports into an npm-installed project without upgrading the entire compatible package set.

Verify

bun run type-check
bun run dev
curl http://localhost:3000/health

Continue to sell a paid API.

Install Lucid