# x402 Machine Payment Surface

DoNotAct keeps the account/API-key/Stripe path as the main access membrane. The
x402 surface is live for agents that should pay per request without a user
account.

The canonical route is also indexed in CDP Bazaar after a standard CDP/x402
settlement, so agent marketplaces can discover the paid resource instead of
scraping the homepage.

Canonical x402 route:

```text
GET /x402/v1/dispute/{venue}/{market_id}
```

This route follows x402 v2 when the client can create a valid x402
`PaymentPayload`. The client handles the `Payment-Required` header, creates the
payload, then retries the same request with:

```text
PAYMENT-SIGNATURE: <base64 x402 PaymentPayload>
```

The standard CDP/x402 path has been validated end to end on the canonical route:
challenge, `PAYMENT-SIGNATURE` retry, CDP facilitator settlement, paid response,
and `DO_NOT_ACT` / `UMA_DISPUTE_DETECTED` diagnostic output. This is the route
agents should prefer when their x402 client can build a v2 payment payload.

For Python/custom agents that can pay USDC on Polygon but cannot yet construct
an x402 payload, the same canonical route also accepts a verified transaction
hash:

```text
GET /x402/v1/dispute/{venue}/{market_id}
X-402-Tx-Hash: 0x...
```

The server verifies the hash on-chain, requires the exact USDC transfer to the
configured receiving wallet, and consumes the hash once.

This tx-hash flow has been validated end to end with an external payer wallet:
challenge, exact Polygon USDC transfer, retry with `X-402-Tx-Hash`, one-time
hash consumption, and a paid diagnostic response.

## Fast path for custom agents

If your agent does not yet ship an x402 SDK, use this deterministic bridge:

1. `GET https://donotact.com/x402/v1/dispute/polymarket/580810`.
2. Read the `Payment-Required` challenge. Treat `network`, `asset`,
   `amount`, and `pay_to` as the source of truth for the payment.
3. Send the exact Polygon USDC transfer to the challenge `pay_to` address.
4. Wait for confirmation.
5. Retry the same URL with `X-402-Tx-Hash: 0x...`.

The payment sender can be any wallet. The receiver, asset, network and amount
must match the challenge exactly. Do not send to a remembered wallet, do not use
USDC.e when the challenge asks for native Polygon USDC, and do not reuse a hash.

Expected outcomes:

| HTTP | Meaning | What to do |
|---:|---|---|
| `402` on first call | Normal challenge | Pay the exact challenge, then retry. |
| `200` with `payment.settlement=verified_on_chain_and_consumed_once` | Paid diagnostic delivered | Store the diagnostic and receipt. |
| `409 tx_hash_already_consumed` | The hash was already used | Do not retry that hash; create a new payment for a new call. |
| `402` after retry | Payment proof rejected or not confirmed | Check network, asset, amount, receiver and confirmations. |
| `503` | Settlement not configured or temporarily unavailable | Fail closed and retry later. |

Most failed custom integrations come from one of four mistakes: wrong receiver,
wrong token variant, unconfirmed transaction, or hash replay. The challenge is
the contract for the payment.

Polygon tx-hash compatibility route:

```text
GET /x402/tx/v1/dispute/{venue}/{market_id}
X-402-Tx-Hash: 0x...
```

This alias remains for agents that already integrated the tx-hash bridge before
the canonical route accepted `X-402-Tx-Hash`. It performs the same on-chain
verification and one-time consumption as `/x402/v1/dispute/...`.

Current production settings:

- network: `eip155:137` (Polygon mainnet)
- facilitator: `https://api.cdp.coinbase.com/platform/v2/x402`
- price: `$0.01` / 0.01 USDC
- asset: Polygon USDC
- CDP Bazaar status: indexed after standard x402 settlement

Runtime settings:

```text
DONOTACT_X402_ENABLED=true
DONOTACT_X402_PAY_TO=0x...
DONOTACT_X402_NETWORK=eip155:137
DONOTACT_X402_PRICE=$0.01
DONOTACT_X402_FACILITATOR_URL=https://api.cdp.coinbase.com/platform/v2/x402
DONOTACT_X402_FACILITATOR_BEARER_TOKEN=
DONOTACT_X402_CDP_API_KEY=
DONOTACT_X402_CDP_API_SECRET=
DONOTACT_POLYGON_RPC_URL=https://polygon.drpc.org
```

The backend only needs a public receiving address. Do not place wallet seed
phrases or signing material in the DoNotAct runtime. If required settings are
missing, `/x402/v1/dispute/...` fails closed instead of accepting payment.

Settlement requires a facilitator that supports the configured network and
scheme. CDP's authenticated facilitator has been verified to support EVM
`exact` on Polygon mainnet (`eip155:137`).

For CDP's authenticated facilitator, prefer `DONOTACT_X402_CDP_API_KEY` and
`DONOTACT_X402_CDP_API_SECRET`. The app derives short-lived JWT authorization
headers per facilitator request instead of relying on a fixed bearer token.

Dependency note: the app uses `x402[evm]` rather than the `x402[fastapi]` extra,
because the FastAPI extra currently requires a newer FastAPI than the app pins.
The base middleware is imported directly and remains compatible with the current
app after build verification.

Tx-hash compatibility boundaries:

- only Polygon mainnet is accepted;
- only Polygon USDC transfers are accepted;
- amount must equal the configured price exactly;
- receiver must equal the configured DoNotAct wallet;
- payer may be any wallet as long as the on-chain transfer satisfies the
  challenge;
- failed/pending/unconfirmed transactions fail closed;
- each transaction hash can unlock at most one diagnostic response;
- replay returns `409 tx_hash_already_consumed`.

Verified standard CDP/x402 proof:

- route: `/x402/v1/dispute/polymarket/580810`
- payment header: `PAYMENT-SIGNATURE`
- payer: external test wallet
- settlement tx: `0x053c1afd61a136c1b0d32941243b871b08941202504d54c27e0ed22fb113880b`
- response: HTTP `200`
- payment response header: present
- diagnostic result: `DO_NOT_ACT` with `UMA_DISPUTE_DETECTED`
- CDP Bazaar search: indexed under `DoNotAct`, `donotact.com`, and `dispute risk polymarket`

Verified tx-hash compatibility proof:

- route: `/x402/tx/v1/dispute/polymarket/580810`
- payer: `0x693db633e979e412FD4C5E273fE891F9b4F71Cb9`
- tx hash: `0xacb3fb25fdc78a5c97da89c00a4bb66613109922096064902644bd16f7ac129a`
- settlement: `verified_on_chain_and_consumed_once`
- diagnostic result: `DO_NOT_ACT` with `UMA_DISPUTE_DETECTED`

Machine-readable proof: `/examples/x402-payment-proof.json`

This proof demonstrates payment transport and one-time settlement. It is not a
profit, ROI, avoided-loss, fill-quality, alpha, or demand claim.

---

## Agent Discovery

- llms.txt: `/llms.txt`
- Full context: `/llms-full.txt`
- Agent manifest: `/agent.json`
- OpenAPI: `/openapi.json`
- Discovery docs: `/docs/discovery`