Accept a payment
The core Prudra integration is three middleware functions chained together on any Express route.walletMiddleware identifies which wallet receives payment. payMiddleware handles the 402 challenge and verification. vaultMiddleware creates the vault where your handler stores its output.
- Dashboard
- SDK
- cURL
Dashboard support for managing paid endpoints is coming soon. Use the SDK or cURL to set up payment-gated routes.
Middleware parameters
walletMiddleware
| Parameter | Type | Required | Description |
|---|---|---|---|
walletId | string | Yes | The ID of the wallet that receives payment. BYO wallets: byw_.... Managed wallets: mwt_.... |
walletMiddleware globally (for all routes) or per-route. If mounted globally, it runs once for all routes. If mounted per-route, you can use different wallets for different endpoints.
payMiddleware
| Parameter | Type | Required | Description |
|---|---|---|---|
price | string | Yes | The payment amount in USD. e.g. "0.01" for $0.01. |
description | string | No | Human-readable description shown in payment UIs. |
acceptSessions | boolean | No | Enable session payments. Requires Pro plan. Default: false. |
vaultMiddleware
No required parameters. The vault is created automatically and attached toreq.vault.
What gets set on req
After the middleware chain runs, your handler has access to:
| Property | Type | Description |
|---|---|---|
req.payment | object | Payment details: protocol, amount, txHash, vaultId, paymentId, sessionId |
req.vault | Vault | The vault instance. Call .addDocument(), .addFile(), .emit(), .seal(), .persist() |
req.wallet | object | The wallet that received payment: id, address, chain |
req.sessionId | string | undefined | Set when the request is part of a session |
The vault in your handler
The vault attached toreq.vault is ready to use immediately. Common operations:
Error handling
| Error | HTTP status | Cause | Resolution |
|---|---|---|---|
payment-required | 402 | No payment credential in request | Expected — agent must pay |
payment-verification-failed | 402 | Invalid payment credential | Agent’s signature or tx invalid |
duplicate-payment | 409 | Same txHash used twice | Replay attack prevented |
vault-quota-exceeded | 429 | Active vault limit reached | Seal existing vaults or upgrade |
challenge-rate-limit | 429 | Too many challenges from this IP | Wait 60 seconds |
Next steps
- How x402 works — deep dive on the ERC-3009 signing flow
- How MPP works — the Tempo transaction and challenge verification
- Add session payments — one payment per multi-step workflow
- Add documents to a vault — all vault document options

