x402 Payments

x402 is an open payment protocol built around HTTP 402 Payment Required. Instead of creating an account or copying an API key, a service can describe a price and accepted on-chain payment. Minara can pay that charge with your managed wallet and retry the original request with a bound payment proof.

Core concepts

Minara binds a captured challenge to the current user, request, merchant, amount, asset, network, and expiry. A model cannot replace those fields when it requests payment.

Pay once

1. Call a Minara data tool, paid API, or MCP tool.
2. If it returns payment_required, review the provider, resource, asset amount, network, and recipient shown by Minara.
3. Approve the payment.
4. Minara creates the standard x402 proof and retries the identical original request once.
5. Review the resource result and settlement or transaction status.

Example prompts:

Get the paid market report. If it requires x402, show me the charge and pay it once.

Use my connected research MCP to fetch the premium dataset and handle its x402 charge.

Standard and legacy payments

Standard x402 v2 exact payments use:

• EVM EIP-3009 transferWithAuthorization, signed as EIP-712 typed data.
• A signed Solana token-transfer transaction for SVM networks.
• PAYMENT-REQUIRED, PAYMENT-SIGNATURE, and PAYMENT-RESPONSE headers.

An older service may explicitly request a transaction-hash proof and declare the HTTP header that accepts it. Minara marks those challenges as retry_supported, checks the transfer against the declared amount, recipient, asset, and network, then binds the resulting hash before one retry. If the service does not declare a safe proof header, Minara does not transfer or claim that the resource can be unlocked. A generic HTTP 402 never uses this path.

Pre-authorize recurring charges

Use x402 pre-authorization when you expect repeated small charges. Set:

• A provider scope when the response has a stable provider ID.
• A domain scope when the endpoint has no provider ID.
• A per-call cap, total USDC budget, expiration, merchant address, and optional chain restriction.

You can list active and historical budgets or revoke one immediately with the /x402 preauth commands. Prefer narrow, short-lived budgets. A new merchant, network, recipient, or charge above the cap does not match the budget.

Paid custom MCP

Add the server through Connectors → Add connectors → Add MCP server by URL or supported configuration. Paid servers use the same Connector setup; do not add wallet keys or payment proofs to the MCP configuration.

When an MCP tool returns a valid JSON-RPC x402 challenge, or a direct remote connection returns HTTP 402, Minara exposes the charge, creates a bound proof, and retries the same MCP call. JSON-RPC works with local stdio; HTTP payment headers require a direct remote connection or a broker that forwards them unchanged.

Supported scope and troubleshooting

Minara currently supports x402 exact with assets from its trusted payment registry, including canonical USDC on supported EVM/Solana networks and USD₮0 on X Layer. It matches the merchant's accepted assets against current holdings, rechecks the selected balance before signing, and prefers USDC when equally fundable. It does not support upto, Permit2, aggr_deferred, arbitrary unregistered tokens, or silently changing providers after payment.

• Unsupported scheme, asset, or network: choose a registered exact acceptance or ask the service to publish one.
• Insufficient balance: fund the wallet on the selected network; do not switch chains unless the server offered that chain.
• Challenge expired or changed: make a fresh resource request and review the new charge.
• Payment uncertain: check payment status before retrying. Do not create a second payment while the first result is unknown.
• Proof rejected: do not fall back to a blind transfer. Ask the service to verify its x402 implementation.

For Connector setup and transport restrictions, see Custom MCP and Connector troubleshooting.