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

> Gasless merchant top-ups over x402

The Merchant Top-up Gateway turns a single x402 payment into an onchain action on a third-party ("merchant") contract. The buyer signs a gasless EIP-3009 USDC authorization on Base, Optimism, or Ink; Meridian settles it to a dedicated Base relayer wallet (bridging through Across when needed); the relayer then performs the merchant-side fulfillment transaction on the buyer's behalf. The buyer never needs ETH.

The first supported merchant is **AntSeed**: topping up `AntseedDeposits` buyer balances on Base — the one gas-requiring step in AntSeed's otherwise gasless buyer flow. Once the deposit lands onchain, the balance appears in all AntSeed tooling automatically.

## Base URL

```
https://antseed.mrdn.finance
```

A web UI for interactive top-ups is served at the same origin; the endpoints below are the programmatic surface. All endpoints are scoped by merchant id (`antseed`).

## Endpoints

<CardGroup cols={2}>
  <Card title="Create Top-up" icon="bolt" href="/api-reference/topup/create-topup">
    `POST /v1/{merchant}/topups` — x402-paid
  </Card>

  <Card title="Quote Bounds" icon="scale-balanced" href="/api-reference/topup/quote">
    `GET /v1/{merchant}/topups/quote` — free
  </Card>

  <Card title="Top-up Status" icon="magnifying-glass" href="/api-reference/topup/status">
    `GET /v1/{merchant}/topups/{id}` — free
  </Card>
</CardGroup>

## How it works

1. `POST /v1/antseed/topups` with no payment — you receive `402 Payment Required` with one payment-requirements entry per eligible source in `accepts[]`, plus source-specific bounds in `topup.sources[]`. Base is first.
2. Choose a source and sign an EIP-3009 `TransferWithAuthorization` using that source's chain id and USDC domain (a gasless signature — no transaction, no gas). Cross-chain entries carry `extra.destinationChainId: 8453`.
3. Retry the same request with the signed payment base64-encoded in the `X-PAYMENT` header.
4. The gateway settles through Meridian. Optimism and Ink payments enter `bridging` while Across delivers to Base. The gateway measures the exact Base credit and calls the merchant contract (`deposit(buyer, net)` for AntSeed) from its relayer wallet.
5. The response (and `GET /v1/antseed/topups/{id}`) reports the source `settlementTx`, optional Base `fillTx`, Base `depositTx`, and exact credited amount.

## Payment sources

| Source   | Chain id | USDC EIP-712 name / version | Settlement     |
| -------- | -------: | --------------------------- | -------------- |
| Base     |   `8453` | `USD Coin` / `2`            | Same-chain     |
| Optimism |     `10` | `USD Coin` / `2`            | Across to Base |
| Ink      |  `57073` | `USDC` / `2`                | Across to Base |

## Rules worth knowing

* **Buyer = payer.** v1 only allows self top-ups: the `buyer` must equal the address that signed the payment. Requests with a different `buyer` are rejected (`buyer_mismatch`).
* **Fee transparency.** You pay a gross amount; the merchant contract is credited the amount **net of Meridian facilitator and (when applicable) Across fees**, always measured on Base — never assumed. Responses show both `grossAmount` and `netAmount`.
* **Idempotent.** Replaying the same `X-PAYMENT` returns the existing top-up. Each EIP-3009 authorization `(payer, nonce)` is accepted exactly once.
* **Refund path.** If the deposit can no longer succeed after settlement (e.g. credit limit lost to a concurrent deposit), the delivered amount is automatically refunded to the payer on Base. If an Across deposit itself expires, Meridian operations recover the source-proxy refund manually in v1.

<Note>
  The gateway is centralized *execution*, not custody of the merchant
  relationship: it holds funds only between settlement and fulfillment, and
  anyone could run a competing gateway against the same public merchant
  contract. The merchant protocol has no dependency on it.
</Note>