> For the complete documentation index, see [llms.txt](https://peoplescourt.ai/llms.txt). This page is also available as Markdown.

x402 dispute extension

# Add a dispute record to an x402 payment.

The open-source People’s Court SDK binds published dispute terms and a payer’s explicit acceptance to an ordinary x402 payment. If a dispute follows, the integration can produce a canonical evidence packet for an authorized filing.

[View on GitHub](https://github.com/shunhe-wang/peoples-court-x402-disputes)[Open npm package](https://www.npmjs.com/package/@peoples-court/x402-disputes)

Public TypeScript SDK · Apache-2.0 · Package version 0.1.0

Install

## One package, clear boundaries

```
`npm install @peoples-court/x402-disputes`
```

- x402 v2 lifecycle, tested with 2.19–2.21
- Strict declaration and acceptance validation
- Signed offer and receipt inspection
- Canonical, size-bounded evidence packets
- Adapter-based adjudication handoff

[Read the seller integration guide](https://github.com/shunhe-wang/peoples-court-x402-disputes#seller-declaration)

Protocol flow

## Payment stays x402. The dispute record travels with it.

The extension adds an integrity-checkable record around the transaction. It does not replace the facilitator, hold funds, or change ordinary x402 settlement.

1. 01

  ### Declare

  The seller publishes the forum, Rules, claim scope, evidence expectations, filing window, and execution owner with the payment requirement.
2. 02

  ### Accept

  The payer explicitly accepts those exact terms and binds the acceptance to the resource and payment.
3. 03

  ### Settle

  The payment continues through the ordinary x402 verification and settlement flow. People’s Court is not the facilitator.
4. 04

  ### Preserve

  The integration builds a canonical packet that binds the parties, amount, terms, acceptance, and signed payment artifacts.
5. 05

  ### File

  If a dispute arises, an authorized integrator submits the packet through the controlled Partner API path.
6. 06

  ### Decide

  People’s Court applies the recorded consent and Rules, closes the Record, and serves the Award artifact required by the pinned procedure to the actual execution owner.

## What the extension records and checks

- The supplied declaration, acceptance, payment, and settlement fields are mutually consistent.
- The supplied acceptance record is bound to the exact terms, resource, and payment requirement.
- A separately retained or confirmed packet hash detects later changes to the transaction and evidence references.
- The execution owner is named for any later award handoff.

## What it does not establish

- A signer’s identity or authority unless the integration verifies it separately.
- Whether either party performed, breached, or has a valid claim.
- That an ordinary x402 payment can be reversed or refunded.
- That metadata alone opened a case or supplied both parties’ consent.
- That a merchant, platform, or other execution owner carried out an award.

Verified paths

## Live Base-mainnet outcomes, plus a reproducible packet test.

Base mainnet live0.01 USDC · x402r

### Both referral-to-closure outcomes verified

Two captured payments and refund requests opened production cases under an earlier Rules version. In each, both parties filed and an assigned human arbitrator attested to neutrality, reviewed the draft, and signed the Award. A merchant-win Award closed through x402r’s on-chain refusal. A payer-win award was satisfied by the merchant’s post-capture refund; People’s Court verified the receipt and automatically closed the case.

Both transactions succeeded and were independently observed beyond 12 confirmations. They demonstrate the settlement handoff under the historical procedure then in force. New cases require the parties’ exact selected procedure and a separate express appeal waiver for execution after service without the appeal window. A protocol referral must carry supported consent for that procedure.

[View refund transaction](https://basescan.org/tx/0x2f02976154f2a43c42a6c5391a2519337f04cbc5a9651150f4b19d998fce654e)[View refusal transaction](https://basescan.org/tx/0x1f1f170e71260c82af64f5cc0cd37e46447ce786439897bd20925dde6b187f5f)Base Sepolia integration test0.01 test USDC · x402 2.20.0

### Transaction and packet binding reproduced

A dedicated payer sent 0.01 test USDC to a separate merchant through an x402 facilitator. The resulting packet passed integrity checks, the acceptance wallet signature was recovered, and altered resource, transaction, and amount bindings were rejected.

[View integration transaction](https://sepolia.basescan.org/tx/0xd1aa7830aa1c87dccf04e85218a2feebc2b5e4b081eeafcf90ad9aa5b41a8819)

Composition

## Ordinary x402 and x402r stay distinct.

For ordinary x402, the extension preserves a dispute record around a settled payment. The merchant or platform that controls the funds remains responsible for carrying out any award.

x402r is a separate refundable-payment protocol with its own referral and execution semantics. Existing cases retain their recorded authority and execution path. A refund request opens a case under the default procedure: the Rules assign the AI-only procedure for the amount, each party keeps the human appeal, and an Award executes only after the seven-day stay that follows service.

## Bring an x402 integration.

The SDK is public. We provision and scope hosted Partner API credentials for each integration so authority, consent, and filing boundaries are explicit. Before we accept a filing, the integration must present a configured authority record, records of both parties’ consent, and a second confirmation of the exact filing.

Review the Rules,Terms, andPrivacy Notice.

Discuss an integration