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

# Agentic receives

> Run a working x402 merchant server locally — gate a route the way you'd charge an AI agent for an API call or tool use.

<Card title="x402-accept-payments" icon="github" href="https://github.com/Atum-Labs/examples/tree/main/x402-accept-payments">
  Example merchant server — clone and run locally in minutes.
</Card>

This runs an example merchant server that gates a route behind payment — the same pattern you'd use to charge an AI agent for calling an API endpoint or an MCP tool, not just a human-facing page.

## Prerequisites

<AccordionGroup>
  <Accordion title="Node.js 20+">
    npm is included with Node.js.

    ```bash theme={null}
    brew install node
    ```

    Verify:

    ```bash theme={null}
    node -v   # v20.x.x or newer
    ```
  </Accordion>
</AccordionGroup>

### Prerequisites for real settlement

The stub needs no funds. When you settle for real, the merchant is a pure recipient — it holds no keys and moves no funds, so it only needs a valid receive address on the destination chain — see [Prerequisites](/get-started/start-building/prerequisites).

## 1. Clone and install

```bash theme={null}
git clone https://github.com/Atum-Labs/examples.git
cd examples/x402-accept-payments
npm install
```

## 2. Configure

```bash theme={null}
cp .env.example .env
```

The defaults run against a **stubbed settlement** out of the box — no changes needed to run locally.

To test with a real testnet settlement, set `USE_STUB_FACILITATOR=false` and point `FACILITATOR_URL` at the gateway's facilitator prefix (`https://payment-gw.production-testnet.atum.xyz/x402/v1`) — a base URL including `/x402/v1`, since the example appends `/verify` and `/settle` to it. The corridor's contract addresses are then resolved automatically from the gateway's `/v1/defaults`, so you never set them in `.env` (see [Choose an environment](/payment-protocols/environments)).

<Tip>
  To receive real funds, set `DEST_ADDRESS` in your `.env` to your receiving wallet address.
</Tip>

## 3. Start the server

```bash theme={null}
npm run dev
```

This runs a single process: the example merchant on `localhost:4020`, with an **in-process stub** standing in for Atum's x402 facilitator — so the full `402 → pay → 200` flow runs locally with no separate facilitator service, no gateway, and no funds.

You should see:

```
Merchant listening on http://localhost:4020
Facilitator: stub (local, no funds)
```

`GET /paid` is a sample route in the example app (not an Atum API) standing in for whatever you're gating — an API endpoint, an MCP tool, a dataset. Once it's running, the merchant is ready to receive requests from a human's browser, a script, or an AI agent's tool call.

## 4. Test the flow

Request the gated route without paying, and you get `402 Payment Required` with the payment options the merchant accepts (in a `PAYMENT-REQUIRED` header, mirrored in the JSON body for readability):

```bash theme={null}
curl -s http://localhost:4020/paid | jq .
```

To drive a full `402 → pay → 200`, run the [`x402-make-payments`](/payment-protocols/x402/make-payments/agentic-payment-initiation) client against this server — a plain `curl` can't produce the signed credential a payment needs. The exact challenge shape, headers, and amounts are in [`src/merchant.ts`](https://github.com/Atum-Labs/examples/blob/main/x402-accept-payments/src/merchant.ts).

## What's happening

Looking at `src/merchant.ts`:

1. A request arrives at `GET /paid`.
2. If no `PAYMENT-SIGNATURE` header is present → return `402` with the accepted payment options (including the `payment-identifier` extension as required).
3. If a header is present → verify the credential, then settle it.
4. On success → return `200` with the protected content and a `PAYMENT-RESPONSE` settlement receipt. Key delivery on that receipt's `payment_id`.
5. If settlement is still running → return pending (with `PAYMENT-RESPONSE` so the payer can read it) and let them [retry the same purchase](/payment-protocols/idempotency).

In stub mode, verify and settle are short-circuited in-process — no facilitator, gateway, or funds. In real mode the server calls the facilitator's `/verify` and `/settle` instead. Either way it holds no funds and no keys, and the same code path serves a human, a script, or an agent.

## Going to testnet

Settling for real means setting `USE_STUB_FACILITATOR=false` and your `DEST_ADDRESS`, then pointing `FACILITATOR_URL` at `https://payment-gw.production-testnet.atum.xyz/x402/v1` — the corridor's contract addresses are fetched from the gateway's `/v1/defaults` automatically, so you don't paste them by hand. See the [example README](https://github.com/Atum-Labs/examples/blob/main/x402-accept-payments/README.md) for `.env` values and on-chain verification — its **Going to testnet / mainnet** section walks through that app. New to Atum's environments? See [Choose an environment](/payment-protocols/environments) for which one to target and what to expect from `production-testnet`. Run through the [pre-flight checklist](/payment-protocols/pre-flight-checklist) before your first real payment.

## Next steps

| Topic                               | Link                                                                                  |
| ----------------------------------- | ------------------------------------------------------------------------------------- |
| Direct integration, no example repo | [Develop with Atum SDK](/payment-protocols/x402/accept-payments/develop-with-the-sdk) |
| Idempotency                         | [Idempotency](/payment-protocols/idempotency)                                         |
| Payer-side guide                    | [Make payments](/payment-protocols/x402/make-payments/overview)                       |
| Facilitator API reference           | [x402 Facilitator API](/api-reference/x402/introduction)                              |
| How settlement works end-to-end     | [Payment lifecycle](/get-started/overview/how-an-atum-payment-works)                  |
| Reconcile a real payment            | [Reconciliation](/get-started/support/reconciliation)                                 |