How-to: Reconcile nanopayments as a seller

As a seller accepting nanopayments, Gateway settles them in batches, so a completed request on your server confirms only that the payment was accepted, not that it settled. Reconcile payments to attribute each settled nanopayment to the request that triggered it, look up a payment’s full state, or produce ledger exports from Gateway’s transfer history.

Prerequisites

Before you begin, ensure that you’ve:

Completed the seller quickstart or the x402 seller integration.
Set up a datastore (database, key-value store, or ledger) where you can record payment metadata.

Steps

Record settlement metadata

Register an onAfterSettle hook to capture attribution data the moment settlement succeeds. If you added nanopayments to an existing x402 server (using x402ResourceServer), register the equivalent hook on your x402ResourceServer instead. The payload and result fields are the same either way.

import { createGatewayMiddleware } from "@circle-fin/x402-batching/server";

const gateway = createGatewayMiddleware({
  sellerAddress: "0xYourSellerAddress",
});

gateway.onAfterSettle(async (ctx) => {
  if (!ctx.result.success) return;

  const authorization = ctx.paymentPayload.payload.authorization as {
    from: string;
    to: string;
    nonce: string;
    value: string;
  };

  // db is pseudocode; replace with your datastore client
  await db.payments.insert({
    // resource.url is the URL the buyer paid for; encode a task or
    // request ID in the path (e.g. /tasks/abc123/output) for attribution
    resource: ctx.paymentPayload.resource?.url,
    // nonce is unique per payment; use it to look up the transfer later
    nonce: authorization.nonce,
    payer: ctx.result.payer,
    amount: ctx.requirements.amount,
    network: ctx.result.network,
    txHash: ctx.result.transaction,
    settledAt: new Date().toISOString(),
  });
});

If your attribution scheme relies on a request header the buyer sends rather than the resource URL, read the header from onProtectedRequest and thread the value through to onAfterSettle using AsyncLocalStorage or a per-request context object.

Look up a payment by nonce

When you need the full transfer record for a single payment, look it up by nonce and then fetch by ID.

import { GatewayClient } from "@circle-fin/x402-batching/client";

const client = new GatewayClient({
  chain: "arcTestnet",
  privateKey: process.env.PRIVATE_KEY as `0x${string}`,
});

async function lookupPayment(resourceUrl: string) {
  const record = await db.payments.findOne({ resource: resourceUrl });
  if (!record) throw new Error(`no payment recorded for ${resourceUrl}`);

  // nonce is unique per payment, so this returns at most one transfer
  const { transfers } = await client.searchTransfers({
    nonce: record.nonce as `0x${string}`,
  });

  const transferId = transfers[0]?.id;
  if (!transferId) return null;

  return client.getTransferById(transferId);
}

Reconcile a date range

Using the GatewayClient from Step 2, search by recipient address and date range, paginate through the results, and match each transfer to a local record by nonce.

async function reconcile(
  sellerAddress: `0x${string}`,
  startDate: string,
): Promise<void> {
  let pageAfter: string | undefined = undefined;

  do {
    const page = await client.searchTransfers({
      to: sellerAddress,
      startDate,
      pageSize: 100,
      pageAfter,
    });

    for (const transfer of page.transfers) {
      const localRecord = await db.payments.findOne({
        nonce: transfer.nonce,
      });

      // Missing localRecord: payment received without attribution
      // Mismatched amount or status: flag for review
    }

    pageAfter = page.pagination?.pageAfter;
  } while (pageAfter);
}

Transfers with no matching local record are typically test payments or direct transfers sent outside the x402 flow.

Handle settlement outcomes

Before treating a payment as final, check transfer.status. Wait for confirmed before crediting the payer for accounting purposes and completed before initiating any dependent onchain operation. Transfers that end in failed were never charged. Do not fulfill the resource in that case.Register an onSettleFailure hook so failed settlements are recorded when they happen rather than surfaced later during reconciliation.

gateway.onSettleFailure(async (ctx) => {
  const authorization = ctx.paymentPayload.payload.authorization as {
    nonce: string;
  };

  await db.paymentFailures.insert({
    nonce: authorization.nonce,
    resource: ctx.paymentPayload.resource?.url,
    error: ctx.error.message,
    failedAt: new Date().toISOString(),
  });
});

Transfer status definitions are in the SDK reference.

Circle CLI

Agent marketplace

x402 facilitators

How-to: Reconcile nanopayments as a seller

Prerequisites

Steps

​Prerequisites

​Steps

Prerequisites

Steps