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

# Smart Contracts

> x402 payment protocol and Meridian facilitator architecture

## Overview

Meridian extends x402 with a **proxy facilitator architecture**. Standard x402 transfers funds directly from payer to recipient; Meridian routes settlement through a facilitator contract instead:

```
Standard x402:  Payer signs authorization → Direct transfer to recipient wallet
Meridian:       Payer signs authorization → Facilitator receives funds → Facilitator settles recipient and fees
```

This one change is what enables fee handling, batch settlement, cross-chain routing, cashback, and organization-scoped payment management on top of the plain x402 flow.

On chains with native EIP-3009 support, Meridian settles standard x402 exact payloads through the facilitator; on chains without an EIP-3009-compatible token (MegaETH, BSC, BOT chain), Meridian settles via Permit2 through `x402ExactPermit2Proxy`. The `upto` scheme (usage-based pricing) settles via Permit2 through `x402UptoPermit2Proxy` on every supported chain. See [Payment Types](/api-reference/payment-types/overview) for how the facilitator routes each payload type.

## X402ProxyFacilitator.sol (V6)

```solidity theme={"system"}
0x8E7769D440b3460b92159Dd9C6D17302b036e2d6
```

The facilitator is a UUPS-upgradeable contract, currently at version 6.

* **Payment Methods**: EIP-3009 `transferWithAuthorization` (USDC), ERC-2612 `transferWithPermit`, and Permit2 `transferWithPermit2` / `transferWithPermit2Upto`
* **Instant Settlement**: Same-chain payments are settled to the recipient during payment execution
* **Batch Settlement**: One signed authorization can settle multiple payments in a single transaction (`batchTransferWithAuthorization` / `batchTransferWithPermit2`), each item with its own recipient, platform, and fee
* **Fee Handling**: Platform and treasury fees accrue inside the facilitator and are withdrawn via `withdrawPlatformFees` / `withdrawTreasuryFees`
* **MRDN Cashback**: On Base, USDC payments earn MRDN cashback priced via Aerodrome TWAP — the rate starts at 2% and decays as total cashback is distributed, capped at \$5 per transaction
* **Cross-Chain Support**: The same entrypoint initiates cross-chain settlement through Across on supported networks, authenticated by a backend-signed EIP-712 message

## x402ExactPermit2Proxy.sol (Non-EIP-3009 Chains)

Integrations on chains without EIP-3009-compatible tokens (MegaETH, BSC, BOT chain) use Permit2 settlement through the Meridian facilitator:

```solidity theme={"system"}
Facilitator:           0x8E7769D440b3460b92159Dd9C6D17302b036e2d6
x402ExactPermit2Proxy: 0x402085c248EeA27D92E8b30b2C58ed07f9E20001
x402UptoPermit2Proxy:  0x402015c795ecb48A360bDC6e35a2EaEb313a0002
Permit2:               0x000000000022D473030F116dDEE9F6B43aC78BA3
```

* **Flow**: Users approve Permit2 once, then sign a Permit2 witness authorization off-chain for each payment
* **Token model**: `paymentRequirements.asset` is the ERC-20 token address being paid
* **Facilitator binding**: `payTo` and `witness.to` stay bound to the Meridian facilitator
* **Settlement**: Meridian settles through `transferWithPermit2`, not through the buyer submitting a transaction

### x402UptoPermit2Proxy (upto scheme)

The `upto` scheme uses the same Permit2 flow with `x402UptoPermit2Proxy` as the signed spender (same address on every chain). The buyer authorizes a maximum amount; Meridian settles the actual usage amount through `transferWithPermit2Upto`. Differences from the exact proxy:

* **Witness shape**: `{ to, facilitator, validAfter }` — the extra `facilitator` field binds which contract may choose the settled amount; both `to` and `facilitator` stay bound to the Meridian facilitator
* **Settled amount**: `0 < settleAmount ≤ permit.permitted.amount`, passed by the seller at settle time (`paymentRequirements.extra.settleAmount`); fees and cashback apply to the settled amount only

```mermaid theme={"system"}
sequenceDiagram
    participant User
    participant Token as ERC20 Token
    participant Permit2
    participant Facilitator
    participant ExactProxy as x402ExactPermit2Proxy
    participant Recipient

    Note over User: One-time setup on Permit2 chains
    User->>Token: approve(Permit2, amount or max)
    Token-->>User: Approval recorded

    Note over User,Facilitator: Every payment
    User->>User: Signs Permit2 witness authorization
    User->>Facilitator: Sends signed payment payload

    Facilitator->>ExactProxy: transferWithPermit2(...)
    ExactProxy->>Permit2: settle signed transfer
    Permit2->>Token: transferFrom(user, facilitator, amount)
    Token-->>Facilitator: Tokens moved

    Facilitator->>Recipient: Settle recipient amount and fees
    Facilitator-->>User: Payment complete
```

## X402PaymentRouter.sol (Pay with Any Token)

The payment router lets buyers fund an exact USDC payment with another ERC-20 token. The buyer signs one Permit2 witness over the input token; the router pulls that token, swaps `tokenIn → WETH → USDC` (or `WETH → USDC`), refunds unused input, and pushes the exact USDC output into Facilitator V6\_1. USDC never passes through the buyer's wallet and no USDC signature is required.

The router is scoped to **Base** and **Robinhood Chain** and uses CREATE2 with the same address on both. Its new V6\_1 address will be published after deployment. Use `previewAmountIn(tokenIn, usdcAmount)` to quote the input requirement before signing.

The signed witness fixes the router, facilitator, exact USDC amount, recipient, platform fee, destination chain, payment ID, and start time. Anyone may submit the signed payment, but none of those terms can be changed. Permit2's nonce prevents replay.

* On **Base**, V6\_1 distributes the USDC locally to the payment recipient after fees.
* On **Robinhood Chain**, V6\_1 deposits the USDC into Across and forwards it to the recipient on Base.
* The intended first integration is the top-up gateway: its Base relayer receives the net USDC and deposits it into the selected inference provider.

The input token must have approved canonical Permit2 once. Input tokens with transfer taxes are unsupported because they break exact swap and refund accounting. Native ETH is not accepted; wrap it to WETH first.

## Solana (SVM)

On Solana, Meridian settles through the `meridian_x402` program instead of a
Solidity facilitator. Solana needs no EIP-3009: a transaction can carry multiple
signers, so the payer signs the settlement transaction as their USDC token
authority and the facilitator co-signs as fee payer and submits it. Settlement
is atomic — the program splits fees and the recipient's net directly from the
payer's token account in one transaction, with no escrow hop.

The program is live on both `solana` (mainnet) and `solana-devnet`. See
[Solana Program](/payments/solana-program) for the architecture, accounts, and
fee math, and [Solana payments](/ai-skills/solana) for an end-to-end integration
guide.

## How a Payment Flows

1. **Authorization Signing**: Payer signs a payment authorization with amount, recipient context, and network details.
2. **Verification**: Server verifies signature and authorization parameters.
3. **Transfer Execution**: Meridian executes settlement through the facilitator — `transferWithAuthorization` for native EIP-3009 tokens, `transferWithPermit2` via the proxy elsewhere.
4. **Fee Application**: Recipient and fee amounts are handled during settlement processing.

Payments are linked to your organization: API keys authenticate verification and settlement, the recipient wallet is configured in organization settings, and every payment lands in your organization's transaction history in [Command Centre](/command-centre/transactions).