Payment element
The Payment element attaches a payment requirement to specific tools or methods on a surface. The gateway intercepts matching requests and demands a verifiable payment receipt before forwarding them upstream. On first failure it returns a 402 challenge. Once the caller settles, the receipt is verified and the request proceeds.
Available on MCP and A2A surfaces only. Drop it on the Managed Agent request edge. Dropping the element enables payment for the surface.
Panel
The sidebar panel shows the payment protocol selector, plus a summary and configuration button for whichever protocol is selected.
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Payment Protocol | select | Yes | x402 | The payment protocol for this Payment element. Options: x402 (HTTP 402 paywall) and MPP (Machine Payments Protocol). Both options are always available, including on a newly added Payment element, and switching between them preserves each protocol’s own configuration. |
x402 panel
The summary displays the current Verification mode, Settlement mode, Networks count, and Requirements count. These values are read-only in the panel. Use the Configure x402 Paywall… button to open the fullscreen editor and change them.
MPP panel
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
| Realm | string | No | — | Protection space sent on the 402 challenge. |
| HMAC Secret Key | select (Secrets store) | No | — | Base64-encoded HMAC-SHA256 key used for stateless challenge binding. Selected from the Secrets store; the gateway resolves it server-side and never stores the raw value in the surface config. |
| Challenge TTL (seconds) | integer | No | 300 | How long an issued 402 challenge remains valid. |
| Payment Methods | read-only list | — | — | The currently configured payment methods. Read-only here; configure them in the Configure MPP… fullscreen editor. |
The panel’s Summary also shows the current Crypto Verification Mode and whether a Stripe secret key is set. Use the Configure MPP… button to open the fullscreen editor and change any of these values.
Configure x402 paywall
Click Configure x402 Paywall… in the panel to open the fullscreen editor. The editor is divided into four areas.
Verification and settlement
| Field | Type | Default | Description |
|---|---|---|---|
| Verification Mode | select | Level 0 - No verification (For testing only) | How the gateway checks payment receipts. Options: Level 0 - No verification (For testing only), Level 1 - Verify cryptographic signature, Level 2 - Gateway verifies on-chain, Level 3 - Facilitator via Fabric Gateway, Level 4 - Facilitator via external provider. |
| Settlement Mode | select | None | How settled funds are processed. Options: None, Deferred, Immediate. Disabled and fixed to None when Verification Mode is Level 0 - No verification (For testing only). |
| Minimum Confirmations | integer (0–100) | 0 | Number of block confirmations required before accepting a payment. 0 accepts mempool transactions. Shown only when Verification Mode is Level 2 - Gateway verifies on-chain. |
| Accept Mempool Transactions | checkbox | On | When on, accepts unconfirmed transactions. Disabled automatically when Minimum Confirmations is above 0. Shown only when Verification Mode is Level 2 - Gateway verifies on-chain. |
| Facilitator URL | string (URL) | https://www.x402.org/facilitator | URL of the external facilitator service. Shown when Verification Mode is Level 4 - Facilitator via external provider. |
| Facilitator Gateway | select | — | Connected gateway to use for verification and settlement via DIDComm. Shown when Verification Mode is Level 3 - Facilitator via Fabric Gateway. |
Crypto network payment options
Add one or more blockchain networks to accept payments on. Select a network from the Mainnets or Testnets list to add it. For each added network, click a token badge to create a payment requirement for that token.
Payment requirements
Each payment requirement defines one acceptable payment option. Callers choose one option from the list you define. Selecting a token badge under Crypto Network Payment Options adds a requirement for that token with the Amount empty.
The gateway accepts an x402 payment only when it names one of these requirements exactly: the same scheme, network, token, recipient, and amount, and the same token transfer details that the requirement carries. Every Verification Mode applies this check, and the transaction record and settlement use the matched requirement.
A surface with x402 payment and an empty list of payment requirements, or with a requirement whose Amount is non-numeric, rejects every payment, so every paid request stops at the gateway. The editor flags both cases: x402 payment is enabled but no payment options are defined and Each x402 payment option must set a charge amount greater than zero.
| Field | Type | Description |
|---|---|---|
| Amount in denomination | string | Payment amount expressed in the network’s smallest denomination unit (for example, USDC uses 6 decimal places, so 1000000 equals 1.00 USDC). The label names the unit, and Actual Cost beside it shows the converted value. |
| Recipient | select | Destination wallet address from your configured recipient addresses. |
| Scheme | select | How the amount is interpreted. Exact requires the caller to pay the specified amount exactly. Up To treats the amount as a maximum: the caller’s payment must authorise exactly that amount as its limit. |
| Transaction Timeout | select | How long the gateway waits for the transaction to appear on-chain. Options: 30 seconds, 1 minute, 2 minutes, 5 minutes, 10 minutes. |
Payment triggers
Payment triggers define which operations require payment. The trigger editor shown depends on the surface protocol. See the relevant sub-section below.
MCP surfaces
The editor defaults to Charge tools matching regex with no patterns. You must either add at least one pattern or switch to Charge all tools before the surface can be saved.
| Field | Type | Description |
|---|---|---|
| MCP Payment Trigger Mode | select | Scope of tools/call requests that require payment. Options: Charge all tools: every tools/call requires payment. Charge tools matching regex: only calls where the tool name matches one of the patterns below. Charge all EXCEPT regex matches: all calls except those whose tool name matches a pattern. Free methods such as tools/list and initialize are never charged. |
| Patterns | string (regex) | One or more regex patterns used with Charge tools matching regex or Charge all EXCEPT regex matches modes. At least one non-empty pattern is required when either of those modes is selected. |
A2A surfaces
The A2A triggers editor is split into two groups.
Command Messages: configure payment for message/send and message/stream operations. For each, add optional regex patterns to match against message content. If no patterns are specified, all requests for that method require payment.
Control Messages: select individual control operations (for example tasks/get, tasks/cancel) that require payment. Control methods do not have message content to match against.
A request whose body the gateway cannot match against these filters, meaning a non-JSON body, a JSON-RPC batch, or a body missing a method name, requires payment. A request with no body passes free of charge. When the Access Point’s Message validation is set to JSON-RPC envelope or Envelope + A2A fields, the gateway refuses such a request before it reaches payment. A surface that receives the request from a connected gateway over Fabric runs the payment check without this envelope check, so such a request can still require payment there.
Configure MPP paywall
Click Configure MPP… in the panel to open the fullscreen editor.
Payment methods
Each payment method defines one way this surface can accept payment, added as a card in the editor. A collapsible View as JSON preview is also available once at least one method is configured.
| Field | Type | Description |
|---|---|---|
| Method Type | select | Crypto methods (tempo, crypto, evm) are verified according to the Crypto Verification Mode below. Card methods (stripe, and legacy card) require the Stripe Secret Key below. |
| Intent | string | Free-text intent label, for example charge. |
| Currency | string | Currency code, for example USDC for a crypto method or usd for a card method. |
| Amount | string | For a crypto method, an integer amount in the currency’s base units, for example wei for ETH or 6-decimal units for a token like USDC; a decimal amount is rejected. For a card method, a decimal major-unit amount, for example 0.01 for one cent. |
| Recipient | string | Destination address for a crypto method, or a connected Stripe account ID for a card method. |
| Network (CAIP-2) | select | Shown for crypto methods only. Choose a mainnet or testnet preset, or enter a custom CAIP-2 network ID. |
Card and on-chain verification
| Field | Type | Default | Description |
|---|---|---|---|
| Stripe Secret Key | select (Secrets store) | — | Required when a card or stripe payment method is configured. Selected from the Secrets store; resolved server-side and never stored in the surface config. |
| Crypto Verification Mode | select | passthrough | How the gateway verifies crypto payment methods. Options: Passthrough (no verification, development only), On-chain (verify the receipt over RPC), Signature (offline EIP-3009 / Permit2), Full (signature and on-chain). Card and Stripe methods are unaffected by this setting. A mainnet crypto payment method cannot be saved while this is set to Passthrough. |
| Verification Timeout (ms) | integer | 10000 | How long the gateway waits for on-chain verification before failing. |
| Minimum Confirmations | integer | 0 | Shown only when Crypto Verification Mode is On-chain or Full. A mainnet crypto method requires at least 1 confirmation. |
| RPC Endpoints (JSON) | JSON object | — | Shown only when Crypto Verification Mode is On-chain or Full. Maps a CAIP-2 network ID to an RPC URL, used to fetch and verify the transaction receipt. |
Payment triggers (MPP)
Payment triggers define which operations require payment. Leaving this section empty means no requests require payment. The trigger editor shown depends on the surface protocol.
MCP surfaces (MPP)
Only tools/call requests can be charged.
| Field | Type | Description |
|---|---|---|
| MCP Payment Trigger Mode | select | Options: Charge all tools, Charge tools matching regex, Charge all EXCEPT regex matches. |
| Patterns | string (regex) | One or more regex patterns, used with the matching or exclude modes. |
A2A surfaces (MPP)
Select individual A2A methods that require payment, with optional regex patterns to filter by message content. Leave this empty to keep A2A free of charge. As with x402, a request with a body the filters cannot match requires payment, and a request with no body passes free of charge.
Related
- Managed Agent reference: where to add the element on the canvas.
Glad to hear it. Thanks for letting us know.
Sorry to hear that. Thanks for letting us know.
Still stuck? Ask the community on Discord or contact us.