Test x402 Payments

An x402 paid resource first returns 402 Payment Required with payment requirements. Agent Payments completes payment within policy, budget, approval, and signer controls, then repeats the same HTTP request with a payment signature. Purchases support HTTPS GET, POST, PUT, PATCH, and DELETE requests.

Complete the quickstart first and verify that runtime MCP and the signing sidecar are healthy. For the first purchase, use a Sandbox wallet with a small test balance and require human approval.

This tutorial uses Base Sepolia USDC. If another paid service requires a different network, confirm that its payment requirement matches a network and USDC in the supported scope, then start with a small payment that requires human approval.

1. Inspect payment requirements

The panel below reads the 402 challenge returned for the resource URL, HTTP method, query parameters, and request body you enter. Network, asset, amount, recipient, and payment scheme come from the response. The panel does not assume Base Sepolia, USDC, or exact. It does not hold a private key, create an Intent, or pay from the browser.

The inspector intentionally accepts a broader range of challenges than Agent Payments can purchase. Successfully displaying a challenge does not mean it is purchasable: the payment requirement must still use a supported x402 version, scheme, HTTPS method, network, and USDC asset. Preview the purchase to learn whether StableOps can proceed before approving any payment.

Cross-origin services must also allow the documentation origin, selected method, and Content-Type, and expose PAYMENT-REQUIRED or X-PAYMENT-REQUIRED through Access-Control-Expose-Headers. Otherwise, the browser cannot read the complete challenge.

2. Ask the Agent to preview a resource

If you already have a paid resource, use its complete HTTPS URL including path and query parameters. Otherwise, ask the Agent to discover candidates. Give this instruction to the Agent with runtime MCP configured:

Use StableOps Agent Payments MCP to prepare one Sandbox x402 payment.

- Target URL: <enter the complete HTTPS URL, or discover candidates and let me choose>
- HTTP method: POST
- Content-Type: application/json
- Exact request body: {"query":"stablecoins","limit":10}
- Check runtime identity, supported networks, budgets, and signing sidecar health
- Preview the exact selected URL
- Show the URL, network, asset, amount, recipient, policy decision, warnings, and projected budget
- Save the preview_token returned by preview
- Do not create a payment Intent until I confirm

The Agent calls stableops_preview_x402_purchase. Preview is read-only. It creates no payment Intent and reserves no budget. For non-GET requests, the opaque preview_token also binds the method, exact request body, and content type. The body stays in MCP memory and is sent directly to the resource service. StableOps receives only its SHA-256 digest and content type. Before continuing, verify the method, exact URL, body, network, asset, amount, and recipient. Stop if preview rejects the purchase or returns an unexpected requirement.

The SDK exposes the same behavior directly:

const result = await agent.x402Fetch('https://resource.example.com/search', {
  method: 'POST',
  body: JSON.stringify({ query: 'stablecoins', limit: 10 }),
  contentType: 'application/json',
  idempotencyKey: 'research-task-284:search:v1',
})

Pass strings or exact Uint8Array bytes. Agent Payments hashes and replays those exact bytes. It does not serialize JavaScript objects for you. A non-GET request without a body is supported and is bound to the SHA-256 digest of an empty body. GET requests cannot carry a body or content type.

3. Confirm and purchase

After reviewing preview, tell the same Agent:

Confirm the purchase of the exact URL just previewed.
Use the same preview_token and set idempotency_key to x402-first-purchase-001.
Do not change the method, URL, query parameters, request body, content type, recipient, or maximum amount.
If human approval is required, save the intent_id and stop. Do not create another payment.
If payment succeeds, return the resource response and intent_id.

The Agent calls stableops_x402_fetch. The purchase repeats the original request to read the payment requirements again, then rechecks policy, budget, wallet, risk, and preview constraints. After signing, it sends the same method and body with PAYMENT-SIGNATURE. Reuse the same idempotency_key for every retry of one business purchase.

For POST and other non-idempotent business operations, the resource server must return 402 before performing the protected action. The Agent SDK may send the request more than once while discovering and refreshing the challenge. Use the seller's own business idempotency field in the body when the API provides one. StableOps idempotency_key deduplicates payment Intents, not the seller's application-side operation.

4. Handle human approval

If the result is awaiting_approval, review and approve the payment in the StableOps console, then ask the Agent to resume the original payment:

Payment Intent <enter intent_id> has been approved.
Resume the original payment with the original method, exact URL, body, content type, and preview_token.
Do not create a new Intent or change the idempotency_key.

The Agent calls stableops_resume_x402_purchase to resume the original payment. Do not resume a rejected payment.

If MCP restarted, preview the original request again with the same method, exact URL, body, and content type, then use the new preview_token to resume the same intent_id. The Control API compares the method, full URL hash, body digest, content type, and refreshed payment requirements before issuing a grant. The Agent must never replace a pending or uncertain payment with another payment.

5. Verify the result

• paid means the paid HTTP request returned a reliable resource response.
• settled means the control plane confirmed on-chain settlement.
• settlement_unknown means the result remains uncertain. Inspect only the original intent_id and do not pay again.

Ask the Agent to call stableops_get_payment for the original payment and return the resource response, payment state, and receipt. Configure signed Webhooks for asynchronous approval, settlement, and exception updates.