# Charge for your API

Put an x402 paywall in front of an endpoint you already run, and get paid per call.

Section: Guides
Source: https://www.roundhouse.studio/docs/guides/charge-for-your-api

---

Be the resource server. You already have something worth paying for; this adds the `402` in front of
it and the settlement behind it.

**You need:** an endpoint and a wallet address to be paid at. **You do not need:** a merchant
account, a facilitator of your own, or gas.

## 1. Point at a facilitator

The facilitator is what verifies and broadcasts your customers' payments. Roundhouse runs one, free,
no cap, no percentage:

```bash
export X402_FACILITATOR_URL="https://x402.roundhouse.studio"
```

Check what it serves before you build against it — this is the step people skip and then spend an
afternoon on:

```bash
curl -sL "$X402_FACILITATOR_URL/supported" | jq
```

Currently `exact`, USDC, **Base mainnet** (both the `base` and `eip155:8453` spellings). For testnet
development use `https://x402.org/facilitator`, which serves Base Sepolia and **not** mainnet.

## 2. Put the paywall in front

Any standard x402 middleware works, because the facilitator speaks the standard wire format.

```javascript
// Express, with the reference middleware.
import express from 'express';
import { paymentMiddleware } from 'x402-express';

const app = express();

app.use(
  paymentMiddleware(
    process.env.PAY_TO,                        // your wallet
    { 'GET /forecast': { price: '$0.01', network: 'base' } },
    { url: process.env.X402_FACILITATOR_URL },
  ),
);

app.get('/forecast', (req, res) => res.json({ forecast: '…' }));
app.listen(3000);
```

Rolling your own is a `402` with an `accepts` array, then `POST /verify` and `POST /settle` against
the facilitator. Two things to get right if you do:

- **`paymentPayload` is an object** on `/verify` and `/settle`. Base64 is only the `X-PAYMENT`
  header's encoding — hand a facilitator the string and it answers
  `500 No facilitator registered for x402 version: undefined`.
- **Verify before you settle, and settle before you serve.** Returning the resource on a successful
  verify without settling means you were never paid.

## 3. Choose a price

Nothing enforces a price. What you can do is look at what comparable services actually get paid,
which is a question the index answers:

```sql
select e.service_name,
       e.price_usdc                              as listed,
       round(avg(s.amount_usd)::numeric, 4)      as avg_paid,
       count(*)                                  as settlements,
       count(distinct s.payer)                   as payers
from external_resources e
join settlements s on s.payee = e.pay_to
where e.description ilike '%weather%'
  and s.block_time > now() - interval '30 days'
group by 1, 2
order by settlements desc
limit 20
```

Prices cluster low — cents, not dollars — because the buyer is a program deciding call by call, and
the alternative to paying you is usually trying somewhere else.

## 4. Test it end to end

Against your own endpoint, from outside your network:

```bash
# Unpaid: expect 402 with a well-formed accepts array.
curl -isL "https://api.example.com/forecast"
```

Then pay it yourself with any x402 client. If you have never done that, do
[the test drive](https://www.roundhouse.studio/docs/guides/first-x402-payment) first so you are debugging one unknown rather than
two.

## 5. Watch the money arrive

Every settlement the facilitator handles is indexed. Within a few minutes of your first real payment:

```bash
curl -sL "https://www.roundhouse.studio/api/v0/merchants/<your-payTo>" | jq
curl -sL "https://www.roundhouse.studio/api/v0/entities/<your-payTo>/settlements?limit=20" | jq
```

Your merchant page at `/merchant/<your-payTo>` then carries inbound volume, distinct customers,
repeat rate, the
services being paid for, and an activity heatmap. That page is what a prospective buyer reads when
[vetting you](https://www.roundhouse.studio/docs/guides/vet-a-counterparty) — which is the actual exchange for free facilitation:
you get settlement, the record gets a verified row, and you accumulate evidence.

## Design notes worth having

- **One `resource` URL per priced thing.** The index separates service revenue from forwarded value
  by `resource`. Collapsing several products onto one URL makes your own analytics unreadable.
- **Keep `payTo` stable.** It is the join key. Rotating it splits your history into two records that
  nothing reconciles.
- **Free paths stay free.** Health checks, manifests, `/.well-known/*` and previews should not be
  behind the paywall, or crawlers and probes will report you as down.
- **Do not price per byte yet.** Flat per-call is what clients implement; anything cleverer is
  something you will be explaining to every buyer.

## Hand it to an agent

```prompt
Add an x402 paywall to my API and verify it works.

Endpoint: <https://…>
Pay to: <0x…>
Target price: <$0.01>

1. GET https://x402.roundhouse.studio/supported and confirm the scheme,
   network and asset I need are served. If not, stop and tell me.
2. Add x402 middleware to my server, pointed at that facilitator. Show me the
   diff before applying it.
3. Restart, then fetch the endpoint unpaid from outside and show me the decoded
   402 body. Confirm accepts[0] has the right payTo, atomic amount, asset and
   network.
4. Pay it once with a test client and show me the X-PAYMENT-RESPONSE.
5. Confirm the settlement is indexed at
   GET /api/v0/merchants/<payTo> within five minutes.
```

## Next steps

- [Get listed as a merchant](https://www.roundhouse.studio/docs/guides/get-listed-as-a-merchant) — be discoverable
- [Facilitators](https://www.roundhouse.studio/docs/x402/facilitators) — what verify checks, and why it matters
- [Errors](https://www.roundhouse.studio/docs/x402/errors) — what your customers will hit

---

Every page in these docs is available as markdown at its own URL plus `.md`.
Full index: https://www.roundhouse.studio/docs.md