> ## 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.

# Settle Batched Payment

> Settle an x402 payment with organization-specific authentication. This endpoint supports standard exact EIP-3009 EVM payloads, Circle Gateway batched payloads, and the Permit2 payload used on non-EIP-3009 EVM networks.

Settle a Nanopayments Gateway (Circle Gateway batched) payment. This is the same `POST /v1/settle` endpoint used by the default x402 path. The facilitator inspects `paymentRequirements.extra` and forwards batched requests to Circle's Gateway API instead of settling on-chain.

<Note>
  See [Nanopayments Gateway Overview](/api-reference/payment-types/circle-gateway)
  for the end-to-end flow, supported networks, and Gateway Wallet contract
  addresses.
</Note>

## Routing

A request is routed to Circle Gateway when **all** of the following are true:

* `paymentRequirements.extra.name === "GatewayWalletBatched"`
* `paymentRequirements.extra.version === "1"`
* The network is Gateway-enabled (testnets always; mainnets gated by the facilitator's `GATEWAY_MAINNET_ENABLED` flag, currently `true`)

If `extra` indicates batched but the network is not Gateway-enabled, the facilitator returns HTTP 403 with `errorReason: "gateway_not_enabled"`.

## Authentication

Requires `Authorization: Bearer <api-key>`. Recipient is taken from your organization settings or from `paymentRequirements.extra.creditedRecipient`.

## Request Body

```json theme={"system"}
{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b8D0c4E5e6C2aE7A3e",
        "to": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE",
        "value": "10000",
        "validAfter": "1735689600",
        "validBefore": "1736035200",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base",
    "maxAmountRequired": "10000",
    "amount": "10000",
    "resource": "https://example.com/api/sample",
    "description": "Batched payment for 0.01 USDC",
    "mimeType": "application/json",
    "payTo": "0xRecipient...",
    "maxTimeoutSeconds": 345600,
    "asset": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE",
    "extra": {
      "name": "GatewayWalletBatched",
      "version": "1",
      "verifyingContract": "0x77777777Dcc4d5A8B6E418Fd04D8997ef11000eE",
      "creditedRecipient": "0xRecipient...",
      "platform": "0x0000000000000000000000000000000000000000",
      "platformFeeBps": 0,
      "destinationChainId": 8453
    }
  }
}
```

### Field notes

| Field                                   | Notes                                                                                                                                                                        |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `paymentRequirements.asset`             | Set to the **Gateway Wallet contract** for this network (used as `verifyingContract` in EIP-712 signing). The facilitator swaps it back to USDC before forwarding to Circle. |
| `paymentRequirements.maxTimeoutSeconds` | `345600` (4 days) is the recommended Circle Gateway nanopayment validity window.                                                                                             |
| `payload.authorization.value`           | USDC base units (6 decimals). `10000` = `0.01` USDC.                                                                                                                         |
| `extra.name` + `extra.version`          | Required exactly as `"GatewayWalletBatched"` and `"1"`. This is the routing trigger.                                                                                         |

## Response

### 200: Success

The facilitator spreads Circle's response and adds Meridian-specific fields. The exact shape is `{ ...gatewayResponse, settlementMethod, network, testnet, authContext }` after `toJsonSafe()`:

```json theme={"system"}
{
  "success": true,
  "transaction": "0xCircleSettlementTxHash...",
  "network": "base",
  "settlementMethod": "batched",
  "testnet": false,
  "authContext": {
    "authMethod": "middleware_handled",
    "timestamp": "2026-04-30T18:24:11.502Z"
  }
}
```

* `success` and `transaction` (and any other fields) are forwarded from Circle.
* `settlementMethod: "batched"` confirms the Circle Gateway path was taken.
* `testnet` is `true` when `network` is one of `arc-testnet`, `base-sepolia`, `optimism-sepolia`, or `fluent-testnet`.
* `authContext.authMethod` is the literal string `"middleware_handled"`.
* The settle path's `authContext` does **not** include `organizationId` (unlike verify).

### 400: Error from Circle Gateway

When Circle's response has `success: false`, the facilitator forwards it with HTTP 400. The shape is `{ ...gatewayResponse, settlementMethod, network, testnet }` (no `authContext`):

```json theme={"system"}
{
  "success": false,
  "settlementMethod": "batched",
  "network": "base",
  "testnet": false,
  "...": "all other fields are forwarded from Circle (errorReason, message, etc.)"
}
```

### 403: Network not enabled

```json theme={"system"}
{
  "success": false,
  "errorReason": "gateway_not_enabled",
  "error": "Circle Gateway is not supported for network \"<network>\".",
  "transaction": "",
  "network": "<network>"
}
```

### 500: Facilitator-side failure forwarding to Circle

```json theme={"system"}
{
  "success": false,
  "errorReason": "batched_settle_error",
  "error": "<error.message or 'Unknown batched settlement error'>",
  "transaction": "",
  "network": "<network>"
}
```

## Error Codes

* `gateway_not_enabled`: `paymentRequirements.extra` matched batched but `isGatewayEnabledForNetwork(network)` returned `false`.
* `batched_settle_error`: forwarding to Circle threw before a response could be parsed (network error, SDK exception, etc.).
* Any `errorReason` Circle returns: passed through verbatim alongside `settlementMethod: "batched"`.


## OpenAPI

````yaml POST /v1/settle
openapi: 3.1.0
info:
  title: Meridian Protocol API
  description: API for x402 payments
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.mrdn.finance
    description: Production server
security:
  - cookieAuth: []
  - apiKeyAuth: []
paths:
  /v1/settle:
    post:
      summary: Settle x402 payment
      description: >-
        Settle an x402 payment with organization-specific authentication. This
        endpoint supports standard exact EIP-3009 EVM payloads, Circle Gateway
        batched payloads, and the Permit2 payload used on non-EIP-3009 EVM
        networks.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                paymentPayload:
                  $ref: '#/components/schemas/SettlePaymentPayload'
                paymentRequirements:
                  $ref: '#/components/schemas/PaymentRequirements'
              required:
                - paymentPayload
                - paymentRequirements
      responses:
        '200':
          description: Payment settlement result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SettleResponse'
        '400':
          description: Invalid payment data
        '401':
          description: Invalid API key
      security:
        - apiKeyAuth: []
components:
  schemas:
    SettlePaymentPayload:
      description: >-
        Payload accepted by `POST /v1/settle`. Permit2 is currently settle-only;
        the deprecated `POST /v1/verify` endpoint still uses the legacy
        `PaymentPayload` schema.
      oneOf:
        - $ref: '#/components/schemas/ExactEvmPaymentPayload'
        - $ref: '#/components/schemas/Permit2PaymentPayload'
    PaymentRequirements:
      type: object
      required:
        - scheme
        - network
        - maxAmountRequired
        - resource
        - description
        - mimeType
        - payTo
        - maxTimeoutSeconds
        - asset
      properties:
        scheme:
          type: string
          enum:
            - exact
        network:
          type: string
          description: Network identifier
        maxAmountRequired:
          type: string
          pattern: ^\d+$
          description: Maximum amount required in the token's smallest unit.
        resource:
          type: string
          format: uri
        description:
          type: string
          description: Payment description
        mimeType:
          type: string
          description: Content MIME type
        payTo:
          type: string
          description: >-
            Facilitator or recipient address required by the selected payment
            type.
        maxTimeoutSeconds:
          type: integer
          description: Maximum validity window in seconds.
        asset:
          type: string
          description: Payment asset contract address or chain-specific asset identifier.
        extra:
          type: object
          additionalProperties: true
    SettleResponse:
      type: object
      required:
        - success
        - transaction
        - network
      properties:
        success:
          type: boolean
        transaction:
          type: string
          description: Transaction hash on success. Empty string on failure.
        network:
          type: string
        payer:
          type: string
        errorReason:
          type: string
        authContext:
          type: object
          additionalProperties: true
    ExactEvmPaymentPayload:
      type: object
      required:
        - x402Version
        - scheme
        - network
        - payload
      properties:
        x402Version:
          type: integer
          enum:
            - 1
          example: 1
        scheme:
          type: string
          enum:
            - exact
          example: exact
        network:
          type: string
          example: base-sepolia
        payload:
          $ref: '#/components/schemas/ExactEvmPayload'
    Permit2PaymentPayload:
      type: object
      description: >-
        Permit2 payload accepted by `POST /v1/settle` for non-EIP-3009 EVM
        payment tokens.
      required:
        - x402Version
        - scheme
        - network
        - payload
      properties:
        x402Version:
          type: integer
          enum:
            - 1
          example: 1
        scheme:
          type: string
          enum:
            - exact
        network:
          type: string
          enum:
            - megaeth
            - bot-chain-testnet
            - bot-chain
            - bsc
        payload:
          $ref: '#/components/schemas/Permit2Payload'
    ExactEvmPayload:
      type: object
      required:
        - signature
        - authorization
      properties:
        signature:
          type: string
          pattern: ^0x[a-fA-F0-9]+$
        authorization:
          $ref: '#/components/schemas/ExactEvmAuthorization'
    Permit2Payload:
      type: object
      required:
        - signature
        - owner
        - permit
        - witness
      properties:
        signature:
          type: string
          pattern: ^0x[a-fA-F0-9]+$
          description: Permit2 witness signature from the token owner.
        owner:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Token owner address.
        permit:
          $ref: '#/components/schemas/Permit2Transfer'
        witness:
          $ref: '#/components/schemas/Permit2Witness'
        permit2612:
          $ref: '#/components/schemas/Permit2612'
    ExactEvmAuthorization:
      type: object
      required:
        - from
        - to
        - value
        - validAfter
        - validBefore
        - nonce
      properties:
        from:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        to:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        value:
          type: string
          pattern: ^\d+$
        validAfter:
          type: string
          pattern: ^\d+$
        validBefore:
          type: string
          pattern: ^\d+$
        nonce:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
    Permit2Transfer:
      type: object
      required:
        - permitted
        - nonce
        - deadline
      properties:
        permitted:
          $ref: '#/components/schemas/Permit2TokenPermissions'
        nonce:
          type: string
          pattern: ^\d+$
        deadline:
          type: string
          pattern: ^\d+$
    Permit2Witness:
      type: object
      required:
        - to
        - validAfter
      properties:
        to:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
          description: Meridian facilitator address.
        validAfter:
          type: string
          pattern: ^\d+$
    Permit2612:
      type: object
      description: >-
        Optional ERC-2612 permit used to approve Permit2 during first-payment
        flows.
      required:
        - value
        - deadline
        - r
        - s
        - v
      properties:
        value:
          type: string
          pattern: ^\d+$
        deadline:
          type: string
          pattern: ^\d+$
        r:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
        s:
          type: string
          pattern: ^0x[a-fA-F0-9]{64}$
        v:
          type: integer
          minimum: 0
          maximum: 255
    Permit2TokenPermissions:
      type: object
      required:
        - token
        - amount
      properties:
        token:
          type: string
          pattern: ^0x[a-fA-F0-9]{40}$
        amount:
          type: string
          pattern: ^\d+$
  securitySchemes:
    cookieAuth:
      type: apiKey
      in: cookie
      name: siwe-session
    apiKeyAuth:
      type: apiKey
      in: header
      name: Authorization

````