> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payreque.st/llms.txt
> Use this file to discover all available pages before exploring further.

# X402 Autonomous Payments

> Let AI agents pay your invoices and access your payment page without any human interaction — using the X402 protocol and USDC on Base.

# X402 Autonomous Payments

X402 is an open payment protocol that uses the HTTP `402 Payment Required` status code to let AI agents pay for resources autonomously — no checkout page, no human click, no API key exchange.

Your PayRequest page is already X402-compatible. Agents that speak the protocol can discover your payment requirements, sign an authorization off-chain, and settle USDC directly to your wallet in one round trip.

<Info>
  X402 requires your EVM wallet to be connected in Provider Settings. The agent pays to that address directly — PayRequest never holds the funds.
</Info>

## How it works

<Steps>
  <Step title="Agent discovers your payment endpoint">
    The agent reads your `payments.txt` manifest and finds your `x402_payment_endpoint`. Alternatively it calls the discovery JSON at `x402_discovery_url` to get the full payment requirements object.
  </Step>

  <Step title="Agent gets payment requirements (402)">
    The agent sends a `POST` to your payment endpoint without a payment header. PayRequest responds with HTTP `402 Payment Required` and a JSON body describing exactly what to pay:

    ```json theme={null}
    {
      "x402Version": 2,
      "error": "payment_required",
      "accepts": [{
        "scheme": "exact",
        "network": "eip155:8453",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "amount": "1000",
        "payTo": "0xYourWalletAddress",
        "maxTimeoutSeconds": 30
      }]
    }
    ```

    `amount` is in USDC atomic units (6 decimals): `1000` = \$0.001.
  </Step>

  <Step title="Agent signs the payment off-chain">
    The agent signs an ERC-3009 `transferWithAuthorization` message with its wallet — no gas, no on-chain transaction yet. This is just a cryptographic signature authorizing the USDC transfer.
  </Step>

  <Step title="Agent retries with X-Payment header">
    The agent sends the same request again, this time including:

    ```
    X-Payment: base64({"x402Version":2,"payload":{"signature":"0x...","authorization":{...}},...})
    ```
  </Step>

  <Step title="PayRequest verifies and settles">
    PayRequest verifies the signature, then broadcasts `transferWithAuthorization` on Base — moving USDC from the agent's wallet directly to yours. No intermediary. The transaction is final within seconds.
  </Step>

  <Step title="Agent receives confirmation (200)">
    PayRequest responds `200 OK` with:

    ```json theme={null}
    {
      "success": true,
      "onchain_tx": "0xTxHash…",
      "payer": "0xAgentWalletAddress",
      "amount_usdc": 0.001
    }
    ```

    Plus an `X-Payment-Response` header with the settlement receipt.
  </Step>
</Steps>

## Pay a specific invoice

Agents can pay a specific outstanding invoice by hitting:

```
POST /api/v1/x402/yourhandle/invoice/{invoiceId}/pay
```

The `402` response will include the exact invoice amount as the required payment. On success, the invoice is automatically marked as paid in PayRequest.

This is the primary use case: an AI agent receives an invoice email, extracts the invoice ID, pays it autonomously via X402, and the invoice closes — all without a human touching the checkout.

## Discovery endpoints

| Endpoint                                   | Method | Description                                             |
| ------------------------------------------ | ------ | ------------------------------------------------------- |
| `/yourhandle/payments.txt`                 | `GET`  | Human + machine readable manifest                       |
| `/api/v1/x402/yourhandle`                  | `GET`  | JSON discovery: wallets, accepted networks, payment URL |
| `/api/v1/x402/yourhandle/pay`              | `POST` | X402 payment endpoint                                   |
| `/api/v1/x402/yourhandle/invoice/{id}/pay` | `POST` | Pay a specific invoice                                  |

## Supported networks

| Network                | Token | Chain ID           |
| ---------------------- | ----- | ------------------ |
| Base (mainnet)         | USDC  | `eip155:8453`      |
| Base Sepolia (testnet) | USDC  | `eip155:84532`     |
| Solana (mainnet)       | USDC  | `solana:5eykt4...` |

## Settlement

PayRequest settles payments by calling `transferWithAuthorization` on the USDC contract. This moves funds directly from the agent's wallet to yours — PayRequest acts as a broadcast relay, not a custodian.

Settlement uses the Base public RPC by default. No Coinbase CDP account is required.

<Tip>
  You can use Base Sepolia testnet USDC to test X402 payments before going live. Set `X402_TESTNET=true` in your environment to switch endpoints to testnet.
</Tip>

## For developers building agents

If you're building an AI agent that needs to pay PayRequest users autonomously:

1. **Discover** — `GET https://payrequest.me/{handle}/payments.txt` or the JSON discovery endpoint
2. **Get requirements** — `POST` to the payment endpoint, expect a `402` response
3. **Sign** — Use `viem`, `ethers.js`, or any EIP-712 library to sign `TransferWithAuthorization`
4. **Pay** — Retry the `POST` with the `X-Payment` header
5. **Confirm** — `200` response + `X-Payment-Response` header = settled

The full protocol specification is at:

<Card title="X402 spec on GitHub" icon="github" href="https://github.com/PayRequest/payments-txt/blob/main/spec/x402-integration.md">
  Complete request/response format, header schemas, and network reference.
</Card>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Does this require gas fees?">
    No — not for the agent. The agent only signs an off-chain ERC-3009 authorization; it never needs ETH or any gas balance. PayRequest's own wallet broadcasts the `transferWithAuthorization` transaction on Base and pays the (tiny, roughly \$0.001) gas cost itself. Agent developers don't need to fund a wallet with ETH to use X402.
  </Accordion>

  <Accordion title="What wallets can agents use?">
    Any EVM-compatible wallet that can sign EIP-712 typed data. Smart contract wallets (Safe, Coinbase Smart Wallet) are also supported since ERC-3009 handles those signatures.
  </Accordion>

  <Accordion title="Can I set a minimum payment amount?">
    The default per-call amount is \$0.001 USDC. For invoice payments, the amount is always the invoice total. Custom minimum amounts per-user are on the roadmap.
  </Accordion>

  <Accordion title="What if verification fails?">
    If the signature is invalid, expired, or the amount is too low, PayRequest returns another `402` with the `verification_error` field explaining what went wrong. The agent can retry with a fresh signature.
  </Accordion>

  <Accordion title="Is this the same X402 as Coinbase's?">
    Yes — PayRequest implements the [open X402 spec](https://github.com/coinbase/x402) published by Coinbase. Any agent built against that spec works with PayRequest. No Coinbase account is needed on your end.
  </Accordion>
</AccordionGroup>