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

# Overview

> Gas-free, batched USDC nanopayments routed through Circle's Gateway API

The Nanopayments Gateway is Meridian's integration of [Circle Gateway nanopayments](https://developers.circle.com/gateway/nanopayments). The buyer funds a unified USDC balance once on any supported chain, then makes many gas-free, sub-cent (\$0.000001 minimum) payments that Circle batches into a single onchain settlement. Each individual x402 payment is verified instantly by signature, while Circle's Gateway System aggregates the signed authorizations and settles net positions in bulk. The Meridian facilitator wraps Circle's `@circle-fin/x402-batching/server` SDK and exposes it through the standard `/v1/verify` and `/v1/settle` endpoints.

<Card title="Nanopayments Gateway UI" icon="wallet" href="https://nanopayments.mrdn.finance/">
  Deposit and withdraw USDC against the Gateway Wallet contract from a hosted UI.
</Card>

## Endpoints

<CardGroup cols={3}>
  <Card title="Settle Batched Payment" icon="dollar-sign" href="/api-reference/endpoint/batched-settle">
    `POST /v1/settle` settles a batched payment via Circle Gateway.
  </Card>

  <Card title="Verify Batched Payment" icon="check" href="/api-reference/endpoint/batched-verify">
    `POST /v1/verify` verifies a batched payment without settling.
  </Card>

  <Card title="Gateway Status" icon="heart-pulse" href="/api-reference/endpoint/batched-sample">
    `GET /v1/batched-sample` reports Gateway connectivity for diagnostics.
  </Card>
</CardGroup>

The buyer never submits an on-chain transaction at payment time. Funds move from their pre-funded Gateway Wallet balance through Circle's batched settlement. Withdrawals from the Gateway Wallet are subject to a 7-day delay enforced by the Gateway Wallet contract.

## Detection

A payment is routed through the Nanopayments Gateway when **both** of these are present in `paymentRequirements.extra`:

```json theme={"system"}
{
  "extra": {
    "name": "GatewayWalletBatched",
    "version": "1"
  }
}
```

This check is performed by `isBatchPayment()` from `@circle-fin/x402-batching/server` inside the facilitator's `/v1/verify` and `/v1/settle` handlers. There are **no separate URLs** for batched flows. Clients call the same endpoints used for default x402 settlement, and the facilitator inspects `extra` to decide where to forward the request.

## Supported networks

`isGatewayEnabledForNetwork()` returns `true` for every network listed below. Testnets are always enabled, and mainnets are gated by the `GATEWAY_MAINNET_ENABLED` flag in the facilitator (currently `true`). The Meridian facilitator will accept requests for these networks and forward them to Circle.

<Warning>
  Networks listed in the facilitator's CAIP-2 map are **not** currently supported
  by Circle's Gateway API for nanopayments, including `bsc`, `fluent-testnet`,
  `ink`, `megaeth`, and `tempo`. The facilitator will forward the request, but Circle will
  reject it. See Circle's [Gateway Supported
  Blockchains](https://developers.circle.com/gateway/references/supported-blockchains)
  for the authoritative list (column `Nanopayments: Yes`). Networks marked
  with `[!]` below are configured locally but not yet supported by Circle.
</Warning>

### Testnets

| Network                | CAIP-2 chain ID   | Circle domain | Gateway Wallet                               | USDC                                         |
| ---------------------- | ----------------- | :-----------: | -------------------------------------------- | -------------------------------------------- |
| `arc-testnet`          | `eip155:5042002`  |       26      | `0x0077777d7EBA4688BDeF3E311b846F25870A19B9` | `0x3600000000000000000000000000000000000000` |
| `base-sepolia`         | `eip155:84532`    |       6       | `0x0077777d7EBA4688BDeF3E311b846F25870A19B9` | `0x036CbD53842c5426634e7929541eC2318f3dCF7e` |
| `optimism-sepolia`     | `eip155:11155420` |       2       | `0x0077777d7EBA4688BDeF3E311b846F25870A19B9` | `0x5fd84259d66Cd46123540766Be93DFE6D43130D7` |
| `fluent-testnet` `[!]` | `eip155:20994`    |      n/a      | `0x0077777d7EBA4688BDeF3E311b846F25870A19B9` | n/a                                          |

### Mainnets

| Network         | CAIP-2 chain ID | Circle domain | Gateway Wallet                               | USDC                                         |
| --------------- | --------------- | :-----------: | -------------------------------------------- | -------------------------------------------- |
| `ethereum`      | `eip155:1`      |       0       | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48` |
| `base`          | `eip155:8453`   |       6       | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| `optimism`      | `eip155:10`     |       2       | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85` |
| `arbitrum`      | `eip155:42161`  |       3       | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0xaf88d065e77c8cC2239327C5EDb3A432268e5831` |
| `avalanche`     | `eip155:43114`  |       1       | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0xB97EF9Ef8734C71904D8002F8b6Bc66Dd9c48a6E` |
| `bsc` `[!]`     | `eip155:56`     |      n/a      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d` |
| `polygon`       | `eip155:137`    |       7       | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359` |
| `unichain`      | `eip155:130`    |       10      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x078d782b760474a361dda0af3839290b0ef57ad6` |
| `ink` `[!]`     | `eip155:57073`  |      n/a      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x2D270e6886d130D724215A266106e6832161EAEd` |
| `sonic`         | `eip155:146`    |       13      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x29219dd400f2Bf60E5a23d13Be72B486D4038894` |
| `worldchain`    | `eip155:480`    |       14      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0x79A02482A880bCe3F13E09da970dC34dB4cD24D1` |
| `sei`           | `eip155:1329`   |       16      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0xe15fC38F6D8c56aF07bbCBe3BAf5708A2Bf42392` |
| `hyperevm`      | `eip155:999`    |       19      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | `0xb88339CB7199b77E23DB6E890353E22632Ba630f` |
| `megaeth` `[!]` | `eip155:4326`   |      n/a      | `0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE` | n/a                                          |

The Gateway Wallet addresses are deployed by Circle at the same address on every supported EVM chain (verified against [Circle's contract addresses page](https://developers.circle.com/gateway/references/contract-addresses)).

The facilitator forwards batched requests to:

* **Testnet:** `https://gateway-api-testnet.circle.com` (explicit URL passed to `BatchFacilitatorClient`).
* **Mainnet:** the default URL baked into `@circle-fin/x402-batching/server`. The facilitator constructs `new BatchFacilitatorClient()` with no `url` override.

Both clients are lazy-initialized singletons.

## Funding the Gateway Wallet

Buyers fund the Gateway Wallet contract on each source chain they want to spend from. Available balance is unified across deposits, so a single signed payment can be settled from any chain that has been funded.

### Deposit flow

1. `USDC.approve(gatewayWallet, value)`. One-time per source chain.
2. `GatewayWallet.deposit(usdcAddress, value)`. Pulls USDC and credits the depositor's balance. Circle also exposes `depositFor`, `depositWithPermit`, and `depositWithAuthorization` on the wallet contract.
3. After the deposit transaction is finalized onchain, the credit becomes part of `availableBalance` and can be spent. **Time-to-finality is chain-specific**:

   | Chain family                                        | Confirmations   | Approx. time      |
   | --------------------------------------------------- | --------------- | ----------------- |
   | Ethereum, Arbitrum, Base, OP, Unichain, World Chain | \~65 ETH blocks | \~13 – 19 minutes |
   | Avalanche, Sonic                                    | \~1             | \~8 seconds       |
   | HyperEVM, Sei                                       | \~1             | \~5 seconds       |
   | Polygon PoS                                         | \~2 – 3         | \~8 seconds       |

   Source: Circle's [Required block confirmations](https://developers.circle.com/gateway/references/supported-blockchains#required-block-confirmations) table.

<Warning>
  Sending USDC to the Gateway Wallet via a plain ERC-20 `transfer` instead of
  one of the deposit methods will result in **loss of funds**. Always call a
  `deposit*` method on the wallet contract.
</Warning>

### Withdrawal flow

Circle's Gateway Wallet supports two withdrawal paths:

* **Instant** (preferred): submit a same-chain transfer through the Gateway API. Funds round-trip through a burn on the source chain and a mint on the destination (same chain), so the withdrawal still requires a user-signed authorization. Pays only burn-tx gas.
* **Trustless** (fallback for when Circle's API is unavailable): on-chain only, with a 7-day delay enforced by the `withdrawalBlock` value on the Gateway Wallet contract.

The hosted [Nanopayments Gateway UI](https://nanopayments.mrdn.finance/) currently exposes the trustless path:

1. `GatewayWallet.initiateWithdrawal(usdc, value)`. Moves balance from `availableBalance` to `withdrawingBalance` and records `withdrawalBlock`.
2. After `block.number >= withdrawalBlock`, call `GatewayWallet.withdraw(usdc)`. Moves the unlocked amount from `withdrawableBalance` back to the buyer's wallet.

Source: Circle's [Withdrawal documentation](https://developers.circle.com/gateway/references/technical-guide#withdrawal).

### Balance views

The Gateway Wallet exposes per-token, per-depositor views the SDK reads:

| View                  | Meaning                                                     |
| --------------------- | ----------------------------------------------------------- |
| `availableBalance`    | Spendable balance for nanopayments                          |
| `withdrawingBalance`  | Amount in the 7-day delay window                            |
| `withdrawableBalance` | Amount past the delay, ready to claim                       |
| `totalBalance`        | `available + withdrawing + withdrawable`                    |
| `withdrawalBlock`     | Block at which a pending withdrawal becomes withdrawable    |
| `isTokenSupported`    | `true` if the Gateway Wallet accepts deposits of this token |

The hosted [Nanopayments Gateway UI](https://nanopayments.mrdn.finance/) wraps these calls so end users do not have to call the contract directly.

## `extra` field reference

In the Nanopayments Gateway path, only `extra.name` and `extra.version` are read by the Meridian facilitator. They are the routing trigger that `isBatchPayment()` checks. Everything else inside `extra` is **passed through** to Circle's Gateway API verbatim by `transformForGateway()`, which spreads `paymentRequirements` and overrides `network`, `asset`, and `amount` only.

| Field                | Required | Read by Meridian? | Description                                                                                                                            |
| -------------------- | :------: | :---------------: | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`               |     ✓    |    Routing only   | Must be the literal string `"GatewayWalletBatched"`. Together with `version`, it is the trigger for `isBatchPayment()`.                |
| `version`            |     ✓    |    Routing only   | Must be the literal string `"1"`.                                                                                                      |
| `verifyingContract`  |          | No (pass-through) | Gateway Wallet contract address used by the **client SDK** as the EIP-712 `verifyingContract` when signing.                            |
| `creditedRecipient`  |          | No (pass-through) | Forwarded to Circle. Note: in the **default x402 path** Meridian reads this field, but the batched path returns before that code runs. |
| `platform`           |          | No (pass-through) | Forwarded to Circle. The `platform` / `platformFeeBps` settlement logic in the facilitator is not executed in the batched path.        |
| `platformFeeBps`     |          | No (pass-through) | Forwarded to Circle. Gateway batched payments do not currently charge a Meridian platform fee.                                         |
| `destinationChainId` |          | No (pass-through) | Forwarded to Circle.                                                                                                                   |

The buyer-side SDK sets `paymentRequirements.asset` to the Gateway Wallet contract so the EIP-712 domain has the correct `verifyingContract`. `transformForGateway()` swaps that back to the network's USDC address (from `NETWORK_USDC`) before forwarding to Circle, since Circle expects the actual token address.

## Implementation notes

* The facilitator-side glue lives in [`apps/facilitator/src/gateway/index.ts`](https://github.com/meridian-protocol/meridian-protocol/blob/main/apps/facilitator/src/gateway/index.ts). It owns the testnet/mainnet client routing, the Gateway Wallet ↔ USDC asset swap, and the CAIP-2 network mapping that Circle's API requires.
* The deposit/withdraw UI lives in [`apps/circle-gateway`](https://github.com/meridian-protocol/meridian-protocol/tree/main/apps/circle-gateway) and is also hosted at [`nanopayments.mrdn.finance`](https://nanopayments.mrdn.finance/).
* Circle recommends calling `settle()` directly for production batched flows rather than the legacy `verify()` + `settle()` two-step.

## See also

### Meridian

* [Payment Types](/api-reference/payment-types/overview)
* [Settle Batched Payment](/api-reference/endpoint/batched-settle)
* [Verify Batched Payment](/api-reference/endpoint/batched-verify)
* [Gateway Status](/api-reference/endpoint/batched-sample)
* [Roadmap: Circle Nanopayments](/roadmap)

### Circle (authoritative source for the upstream API and contracts)

* [Circle Nanopayments overview](https://developers.circle.com/gateway/nanopayments)
* [Circle Gateway technical guide](https://developers.circle.com/gateway/references/technical-guide)
* [Circle Gateway supported blockchains](https://developers.circle.com/gateway/references/supported-blockchains)
* [Circle Gateway contract addresses](https://developers.circle.com/gateway/references/contract-addresses)