Skip to content
DexterDocs

Accept a Payment

Protect an Express route with a $0.01 USDC payment on Solana. A request without payment receives an x402 challenge. A paid request receives the report and a settlement receipt.

  1. The client requests the resource.
  2. The API returns HTTP 402 and its payment requirements.
  3. The client authorizes payment and retries with its proof.
  4. The API asks the facilitator to verify and settle the payment.
  5. The facilitator returns the settlement result.
  6. After successful settlement, the API returns the resource and receipt.

Install

Use Node.js 20 or newer and a Solana address that you control for payouts. This server only needs the public address.

mkdir paid-api
cd paid-api
npm init -y
npm install @dexterai/x402@5.4.2 express@5

Create the Route

Save this as server.mjs. The price comes from the server configuration on every request, including requests that already carry a payment header.

server.mjs
import express from 'express';
import {
  createX402Server,
  SOLANA_MAINNET_NETWORK,
} from '@dexterai/x402/server';

const payTo = process.env.PAY_TO;
if (!payTo) throw new Error('Set PAY_TO to your Solana payout address');

const payments = createX402Server({
  payTo,
  network: SOLANA_MAINNET_NETWORK,
});
const app = express();
const resourceUrl = process.env.RESOURCE_URL ?? 'http://localhost:3000/report';

app.get('/report', async (req, res) => {
  res.setHeader('Cache-Control', 'no-store');
  try {
    const challenge = await payments.buildRequirements({
      amountAtomic: '10000', // 0.01 USDC, with 6 decimals
      resourceUrl,
      description: 'One sample report',
      mimeType: 'application/json',
    });
    const requirement = challenge.accepts[0];
    if (!requirement) throw new Error('Payment requirements unavailable');

    const signature = req.get('PAYMENT-SIGNATURE');
    if (!signature) {
      res.setHeader('PAYMENT-REQUIRED', payments.encodeRequirements(challenge));
      res.status(402).json(challenge);
      return;
    }

    const verified = await payments.verifyPayment(signature, requirement);
    if (!verified.isValid) {
      res.status(402).json({ error: 'payment_invalid', reason: verified.invalidReason });
      return;
    }

    const settled = await payments.settlePayment(signature, requirement);
    if (!settled.success) {
      res.status(402).json({ error: 'payment_unsettled', reason: settled.errorReason });
      return;
    }

    res.setHeader('PAYMENT-RESPONSE', Buffer.from(JSON.stringify(settled)).toString('base64'));
    res.json({
      report: { title: 'Sample report', summary: 'The paid route is connected.' },
      payment: { transaction: settled.transaction, network: settled.network },
    });
  } catch {
    res.status(503).json({ error: 'payment_service_unavailable' });
  }
});

app.listen(3000, '127.0.0.1', () => {
  console.log('Paid API listening at http://localhost:3000/report');
});

The server verifies and settles before delivering the report. Pass the seller's requirement explicitly to both calls so the amount, recipient, asset, and network remain tied to your offer.

Start and Check

PAY_TO='YOUR_SOLANA_PAYOUT_ADDRESS' node server.mjs

In another terminal:

curl -i http://localhost:3000/report

Expect 402 Payment Required, a PAYMENT-REQUIRED header, and an accepts entry with amount 10000. This check requests a price and spends nothing. If requirements cannot be loaded, the server returns 503; check access to the facilitator's /supported endpoint.

Use the Node buyer example against this URL to make a paid request. A successful response has status 200, the report, and a PAYMENT-RESPONSE header containing the settlement result.

Serve Your Own Result

Replace the sample report with your service's output. Validate inputs before taking payment. For work that can fail after settlement, persist the payment transaction and result under a stable operation ID so a retry can recover the existing purchase.

Set RESOURCE_URL to the public HTTPS URL when deploying. Browser callers also need CORS configured to allow PAYMENT-SIGNATURE and expose PAYMENT-REQUIRED and PAYMENT-RESPONSE.

For metered use across requests, continue with Tabs for Sellers.

Previous

Node.js Tabs

Next

Tabs for Sellers

On this page