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

# How-to: Use nanopayments with x402

> Add gas-free nanopayments alongside your existing x402 onchain payment flows

Nanopayments integrates with existing x402 setups at every layer of the stack.
It is **additive**: it introduces gas-free payments as a new option alongside
standard onchain x402 payments, without replacing them. Sellers automatically
accept both methods, and buyers choose whichever they have funded.

## Install the SDK

```shell theme={null}
npm install @circle-fin/x402-batching
```

## Integration paths

Choose the guides that match your role in the x402 ecosystem.

<CardGroup cols={3}>
  <Card title="Buyer (client-side)" icon="cart-shopping" href="/gateway/nanopayments/howtos/x402-buyer">
    Add nanopayments to your x402 client so it can pay gas-free when servers
    support it
  </Card>

  <Card title="Seller (server-side)" icon="store" href="/gateway/nanopayments/howtos/x402-seller">
    Add gas-free nanopayments to your existing x402 server alongside your
    current payment flows
  </Card>

  <Card title="Facilitator" icon="server" href="/gateway/nanopayments/howtos/facilitator-integration">
    Route Gateway payments alongside onchain payments in your facilitator
    service
  </Card>
</CardGroup>

### Seller (server-side)

Add `BatchFacilitatorClient` and `GatewayEvmScheme` to your existing server.
Your `402` responses then include both standard and Gateway payment options:

```ts theme={null}
import { x402ResourceServer } from "@x402/express";
import { HTTPFacilitatorClient } from "@x402/core/server";
import {
  BatchFacilitatorClient,
  GatewayEvmScheme,
} from "@circle-fin/x402-batching/server";

const server = new x402ResourceServer([
  new HTTPFacilitatorClient({ url: "https://facilitator.example.com" }),
  new BatchFacilitatorClient(),
]);
server.register("eip155:*", new GatewayEvmScheme());
await server.initialize();
```

See [Full seller integration guide](/gateway/nanopayments/howtos/x402-seller).

### Buyer (client-side)

Use `CompositeEvmScheme` to handle both Gateway and standard payments
automatically. The client picks the right scheme based on what the server
offers:

```ts theme={null}
import { ExactEvmScheme } from "@x402/evm/exact/client";
import {
  CompositeEvmScheme,
  BatchEvmScheme,
} from "@circle-fin/x402-batching/client";

const composite = new CompositeEvmScheme(
  new BatchEvmScheme(signer),
  new ExactEvmScheme(signer),
);

client.register("eip155:*", composite);
```

See [Full buyer integration guide](/gateway/nanopayments/howtos/x402-buyer).

### Facilitator

Use `isBatchPayment()` to route Gateway payments to `BatchFacilitatorClient`
while your existing handler covers standard payments:

```ts theme={null}
import {
  BatchFacilitatorClient,
  isBatchPayment,
} from "@circle-fin/x402-batching/server";

const gatewayClient = new BatchFacilitatorClient();

async function handleSettle(payload, requirements) {
  if (isBatchPayment(requirements)) {
    return gatewayClient.settle(payload, requirements);
  }
  return existingOnChainHandler.settle(payload, requirements);
}
```

See
[Full facilitator integration guide](/gateway/nanopayments/howtos/facilitator-integration).

## How routing works

When both payment methods are available, routing is automatic at every layer:

| Layer       | What happens                                                                                                                                                                                                                              |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Server      | The `402` response lists both standard and Gateway options in the `accepts` array.                                                                                                                                                        |
| Client      | `CompositeEvmScheme` checks each option's `extra.name`. If `"GatewayWalletBatched"` is present, it uses `BatchEvmScheme`. Otherwise it uses `ExactEvmScheme`.                                                                             |
| Facilitator | `isBatchPayment()` checks the same `extra.name` field and routes [verify](/api-reference/gateway/all/verify-x402payment)/[settle](/api-reference/gateway/all/settle-x402payment) calls to either Gateway or the existing onchain handler. |

No manual routing code is needed in sellers or buyers. The SDK handles it based
on the payment requirements.