Lucid Agents Docs

Lucid's Next-only Payment-Auth integration and its boundary from the wider MPP draft.

The formal Machine Payments Protocol artifact is draft-httpauth-payment-00, an active individual Internet-Draft. It is not an IETF standard or an IETF endorsement. Implementations can be operational while the protocol still changes.

@lucid-agents/mpp uses pinned mppx 0.8.14. It protects Lucid invoke, stream, and task admission with Payment-Auth credentials and implements the HTTP subset listed below.

Support matrix

Capability	Lucid status	Detail
HTTP `402` + `WWW-Authenticate: Payment`	Supported	Standard challenge emitted through `mppx`
`Authorization: Payment`	Supported	Credential verified before admission
`Payment-Receipt`	Supported	Added after successful authorization/response
Tempo charge	Native	Invoke, fixed-admission SSE, and paid tasks
Tempo TIP-1034 session	Native	One-unit invoke and delivered-unit SSE; tasks intentionally unsupported
Stripe charge	Native	Requires Stripe Business Network secret/profile
EVM/x402-compatible charge	Native	EIP-3009 verification with facilitator or application settlement
Custom method	Supported with verifier	Application owns signature, amount, recipient, settlement, payer, and any session semantics
Lightning descriptor	Descriptor only without verifier	Fails closed without an application verifier
Outbound HTTP client	Supported	Payment-aware Fetch from native `mppx/client` intents
Method negotiation	Supported	Client can select an advertised method with `Accept-Payment`
OpenAPI discovery	Supported	Canonical payment offers project onto invoke/stream operations
Durable challenge/replay store	Supported	SQLite/Postgres adapters and custom atomic store port
MCP/JSON-RPC or WebSocket transport	Not implemented	Lucid binding is HTTP entrypoint routes
Subscription and every upstream extension	Not implemented	Do not infer support from the protocol name

Wire and trust boundary

HTTP/1.1 402 Payment Required
WWW-Authenticate: Payment id="...", realm="...", method="tempo", intent="charge", request="...", expires="..."

Authorization: Payment <base64url-credential>

Native Tempo, Stripe, and EVM methods delegate verification to mppx. A custom method is only a descriptor until verifyCredential() cryptographically verifies the signature, bound request, amount, currency, recipient, method, settlement, and claimed payer. Decode-only logic never authorizes a request.

Replay, idempotency, and storage

Challenge IDs are short-lived, target/body-bound, leased before asynchronous verification, renewed while verification runs, and fenced before consumption. The default store is bounded process memory. Production services inject the SQLite or Postgres challengeStore adapter, or a custom atomic implementation, so replay recovery survives restarts and coordinates workers. A stable MPP_SECRET_KEY remains required so another worker can validate the same challenge.

If a custom verifier performs settlement, it must deduplicate the external side effect with the request's Idempotency-Key. Lucid's target replay and policy accounting occur after verification and cannot undo a duplicated external settlement.

Failure semantics

malformed, expired, unknown, wrong-target, replayed, and rejected credentials fail closed;
a custom method without a verifier fails closed;
method/intent mismatch is a configuration error and does not execute the entrypoint;
custom session methods require application-owned verification and settlement;
unknown external settlement outcomes require provider reconciliation before a retry.

Security and deployment checks

Pin @lucid-agents/mpp, mppx, and the exact draft behavior together.
Set a stable, high-entropy MPP_SECRET_KEY; never log challenges, credentials, receipts, or provider secrets.
Use HTTPS and bind credentials to the method, URL, request/body digest, intent, price, recipient, expiry, and challenge ID.
Keep Stripe/Tempo server secrets out of outbound client bundles.
Test concurrent replay, restart between challenge/retry, wrong-body retry, provider timeout, receipt recovery, and custom-verifier idempotency.
Test the selected durable challenge and Tempo session stores under restart and concurrent lease recovery.

Choosing x402 or MPP

Choose MPP when its credential/intent model and one implemented native or custom verifier match the counterparty. Choose x402 exact, upto, or batch settlement for the documented facilitator-backed paths. MPP EVM charge can accept a compatible x402 exact retry, but the general protocols' credentials and receipts are not interchangeable.

Start with every MPP payment method, then use the complete MPP package reference.

MPP compatibility