> ## 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 x402 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 an x402 payment on-chain after verification. This endpoint executes the actual blockchain transaction to transfer funds according to the x402 payment authorization.

<Note>
  When `paymentRequirements.extra.name === "GatewayWalletBatched"`, this
  endpoint forwards the request to Circle's Gateway API instead of settling
  on-chain. See [Circle Gateway
  (Batched)](/api-reference/payment-types/circle-gateway) for the batched
  payment type and [Payment Types](/api-reference/payment-types/overview) for an
  overview of all routing paths.
</Note>

## Authentication

Requires API key authentication with organization context.

## Recipient

For standard merchant integrations, the wallet that receives settled funds is
configured in your organization settings and tied to your API key. Keep
`paymentRequirements.payTo` set to the Meridian facilitator contract for the
network; do not use `payTo` for your merchant wallet.

Platform and marketplace integrations can route the end payout with
`paymentRequirements.extra.creditedRecipient`. See [Marketplace
Fees](/command-centre/marketplace) for that flow.

## Standard Request Body

```json theme={"system"}
{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base-sepolia",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x742d35Cc6634C0532925a3b8D0c4E5e6C2aE7A3e",
        "to": "0x8e633dBf31adCc7D41BE3e95B7c8DD3526B5235A",
        "value": "1000000",
        "validAfter": "1234567890",
        "validBefore": "1234567899",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "base-sepolia",
    "maxAmountRequired": "1000000",
    "resource": "https://example.com/resource",
    "description": "Payment for resource access",
    "mimeType": "application/json",
    "payTo": "0x8e633dBf31adCc7D41BE3e95B7c8DD3526B5235A",
    "maxTimeoutSeconds": 3600,
    "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
  }
}
```

For EIP-3009 payloads, both `authorization.to` and `payTo` must be set to the
facilitator contract address for the network. For Permit2 payloads, keep
`payTo` and `witness.to` bound to the facilitator.

## Cross-Chain EIP-3009 Request Body

Cross-chain USDC settlement uses the same `POST /v1/settle` endpoint and the
same EIP-3009 payload shape. The payment payload is signed on the source chain
where the buyer has USDC. Set `paymentRequirements.network`, `asset`, and
`payTo` for that source chain, then set `paymentRequirements.extra.destinationChainId`
to the destination chain where Meridian should settle after Across fills the
bridge.

For example, a buyer paying from Ink USDC to a seller receiving on Base uses
`network: "ink"` and `destinationChainId: 8453`:

```json theme={"system"}
{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "ink",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x2222222222222222222222222222222222222222",
        "to": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
        "value": "1000000",
        "validAfter": "1234567890",
        "validBefore": "1234568190",
        "nonce": "0x..."
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "ink",
    "maxAmountRequired": "1000000",
    "resource": "https://seller.example/api/tool",
    "description": "Payment for resource access",
    "mimeType": "application/json",
    "payTo": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
    "maxTimeoutSeconds": 300,
    "asset": "0x2D270e6886d130D724215A266106e6832161EAEd",
    "extra": {
      "name": "USD Coin",
      "version": "2",
      "creditedRecipient": "0x1111111111111111111111111111111111111111",
      "destinationChainId": 8453
    }
  }
}
```

The settlement response transaction hash is the source-chain transaction that
started the Across bridge. The seller receives the destination-chain output
after Across fill and Meridian destination-side settlement.

<Note>
  A seller that accepts payments from multiple source chains should expose one
  `paymentRequirements` object per route in the x402 `accepts` array. A
  Base-source requirement cannot be paid by a buyer who only has USDC on Ink.
  Return an Ink-source requirement with `extra.destinationChainId: 8453` for
  that route.
</Note>

<Warning>
  Cross-chain EIP-3009 currently uses Across exact-input routing. If the seller
  needs to receive an exact destination-chain amount, quote the route and set
  `maxAmountRequired` to include bridge fees.
</Warning>

## Permit2 Request Body

There is no separate `POST /v1/permit2` endpoint. Permit2 payments are settled
through `POST /v1/settle` with the Permit2 payload shape below.

```json theme={"system"}
{
  "paymentPayload": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "exampleNetwork",
    "payload": {
      "signature": "0x...",
      "owner": "0x...",
      "permit": {
        "permitted": {
          "token": "0x...",
          "amount": "12345"
        },
        "nonce": "123",
        "deadline": "12345678"
      },
      "witness": {
        "to": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
        "validAfter": "0"
      }
    }
  },
  "paymentRequirements": {
    "scheme": "exact",
    "network": "exampleNetwork",
    "maxAmountRequired": "12345",
    "resource": "https://example.com/resource",
    "description": "Payment for resource access",
    "mimeType": "application/json",
    "payTo": "0x8E7769D440b3460b92159Dd9C6D17302b036e2d6",
    "maxTimeoutSeconds": 3600,
    "asset": "0x...."
  }
}
```

Permit2 settlement is used for `megaeth`, `bsc`, `bot-chain`,
`bot-chain-testnet`, and `tempo`. If the buyer has not already approved Permit2 for the
token, include the optional `paymentPayload.payload.permit2612` object for
tokens that support ERC-2612:

```json theme={"system"}
{
  "permit2612": {
    "value": "1000000",
    "deadline": "1893456000",
    "r": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "s": "0x0000000000000000000000000000000000000000000000000000000000000000",
    "v": 27
  }
}
```

<Note>
  On chains where the payment token does not expose EIP-3009, use Permit2
  through `x402ExactPermit2Proxy` `0x402085c248EeA27D92E8b30b2C58ed07f9E20001`.
  This is the canonical exact Permit2 proxy from the official [x402
  repository](https://github.com/x402-foundation/x402/tree/main), deployed at
  the same address on supported EVM chains. This includes MegaETH, BSC, and BOT
  chain testnet and mainnet. New integrations should keep `payTo` pointed at the
  facilitator, set `paymentRequirements.asset` to the ERC-20 token address,
  approve Permit2 `0x000000000022D473030F116dDEE9F6B43aC78BA3`, and sign the
  Permit2 witness with the proxy as spender. Your backend should still call
  Meridian `POST /v1/settle`.
</Note>

| Network             | Facilitator Contract                         |
| ------------------- | -------------------------------------------- |
| `arc-testnet`       | `0x8e633dBf31adCc7D41BE3e95B7c8DD3526B5235A` |
| `bot-chain-testnet` | `0x8e633dBf31adCc7D41BE3e95B7c8DD3526B5235A` |
| `bot-chain`         | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `base`              | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `bsc`               | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `base-sepolia`      | `0x8e633dBf31adCc7D41BE3e95B7c8DD3526B5235A` |
| `avalanche`         | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `optimism`          | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `arbitrum`          | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `optimism-sepolia`  | `0x8e633dBf31adCc7D41BE3e95B7c8DD3526B5235A` |
| `polygon`           | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `unichain`          | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `ink`               | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `worldchain`        | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `sei`               | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `hyperevm`          | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `megaeth`           | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `tempo`             | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `monad`             | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |
| `robinhood`         | `0x8E7769D440b3460b92159Dd9C6D17302b036e2d6` |

## Response

### Success Response

```json theme={"system"}
{
  "success": true,
  "transaction": "0x1234567890abcdef...",
  "network": "base-sepolia"
}
```

### Error Response

```json theme={"system"}
{
  "success": false,
  "errorReason": "insufficient_funds",
  "transaction": "",
  "network": "base-sepolia"
}
```

## Error Codes

<div className="error-codes-list">
  * `invalid_payload` - Payment payload format is invalid
  * `invalid_payment_requirements` - Payment requirements format is invalid
  * `insufficient_funds` - Insufficient balance for settlement
  * `unexpected_settle_error` - Unhandled exception during settlement
  * `invalid_transaction_state` - On-chain transaction failed
</div>


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

````