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

# Create Top-up

> Pay with x402 and credit the merchant-side balance

Creates (or resumes) a top-up. Unpaid requests receive `402 Payment Required` with the exact payment requirements to sign; paid requests settle the payment and perform the merchant deposit. Replaying the same `X-PAYMENT` returns the existing top-up idempotently.

## Path

<ParamField path="merchant" type="string" required>
  Merchant id. Currently `antseed`. Unknown merchants return `404 unknown_merchant`.
</ParamField>

## Headers

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`.
</ParamField>

<ParamField header="X-PAYMENT" type="string">
  Base64-encoded signed x402 payment payload. Omit on the first request to
  receive the payment requirements via a 402 response.
</ParamField>

## Body

<ParamField body="buyer" type="string">
  Address to credit on the merchant contract. Defaults to the payment signer.
  Must equal the signer (`authorization.from`) — anything else is rejected with
  `400 buyer_mismatch`.
</ParamField>

<ParamField body="amount" type="string">
  Gross amount in USDC base units (6 decimals, e.g. `"5000000"` = 5 USDC).
  Must match `authorization.value` when paying. Must be within the bounds
  returned by the 402 challenge / quote endpoint.
</ParamField>

## Responses

| Status | Meaning                                                                                                                                                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`  | Deposited. Body is the public top-up row (`state: "deposited"`, `grossAmount`, `netAmount`, source `settlementTx`, optional Base `fillTx`, and Base `depositTx`); settlement details are echoed base64-encoded in the `X-PAYMENT-RESPONSE` header. |
| `402`  | No/invalid payment (fresh multi-source challenge in `accepts[]` + `topup.sources[]` bounds), or settlement failed (fresh challenge — retry with a **new** payment).                                                                                |
| `400`  | Rejected before settlement: `buyer_mismatch`, `wrong_network`, `wrong_recipient`, `invalid_signature`, `authorization_expired`, `amount_mismatch`, `amount_too_low`, `amount_too_high`, … (`errorReason` names the cause).                         |
| `409`  | `authorization_reused` (payment already used), `credit_limit_reached`, or `deposit_failed` (deposit impossible after settlement — the settled amount was refunded, see `refundTx`).                                                                |
| `503`  | Settlement is still unknown or a cross-chain payment is `bridging`. Poll the returned `topupId` or retry with the **same** `X-PAYMENT` after `Retry-After` seconds — do not sign a new payment.                                                    |
| `500`  | `needs_review` — an inconsistent, expired, or timed-out bridge state that requires operator attention.                                                                                                                                             |

<RequestExample>
  ```bash Unpaid (get challenge) theme={"system"}
  curl -X POST https://antseed.mrdn.finance/v1/antseed/topups \
    -H "Content-Type: application/json" \
    -d '{ "buyer": "0xYourAddress", "amount": "5000000" }'
  ```

  ```bash Paid theme={"system"}
  curl -X POST https://antseed.mrdn.finance/v1/antseed/topups \
    -H "Content-Type: application/json" \
    -H "X-PAYMENT: <base64 signed payment>" \
    -d '{ "buyer": "0xYourAddress", "amount": "5000000" }'
  ```
</RequestExample>

<ResponseExample>
  ```json 402 Challenge theme={"system"}
  {
    "x402Version": 1,
    "error": "X-PAYMENT header required",
    "accepts": [
      {
        "scheme": "exact",
        "network": "base",
        "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "payTo": "0x…facilitator",
        "maxAmountRequired": "5000000",
        "resource": "https://antseed.mrdn.finance/v1/antseed/topups?buyer=0xYourAddress",
        "description": "Top up AntSeed buyer deposits for 0xYourAddress…",
        "mimeType": "application/json",
        "maxTimeoutSeconds": 300,
        "extra": { "name": "USD Coin", "version": "2", "creditedRecipient": "0x…relayer" }
      },
      {
        "scheme": "exact",
        "network": "optimism",
        "asset": "0x0b2C639c533813f4Aa9D7837CAf62653d097Ff85",
        "payTo": "0x…facilitator",
        "maxAmountRequired": "5000000",
        "extra": {
          "name": "USD Coin",
          "version": "2",
          "creditedRecipient": "0x…relayer",
          "destinationChainId": 8453
        },
        "…": "…"
      },
      {
        "scheme": "exact",
        "network": "ink",
        "asset": "0x2D270e6886d130D724215A266106e6832161EAEd",
        "extra": { "name": "USDC", "version": "2", "destinationChainId": 8453 },
        "…": "…"
      }
    ],
    "topup": {
      "buyer": "0xYourAddress",
      "amount": "5000000",
      "minAmount": "1250000",
      "maxAmount": "10000000",
      "note": "The credited deposit is the settled amount net of Meridian facilitator fees.",
      "sources": [
        { "network": "base", "evmChainId": 8453, "minAmount": "1250000", "maxAmount": "10000000" },
        { "network": "optimism", "evmChainId": 10, "minAmount": "1750000", "maxAmount": "10000000" },
        { "network": "ink", "evmChainId": 57073, "minAmount": "1750000", "maxAmount": "10000000" }
      ]
    }
  }
  ```

  ```json 200 Deposited theme={"system"}
  {
    "success": true,
    "topupId": "0xf6cd…d723",
    "state": "deposited",
    "buyer": "0xYourAddress",
    "payer": "0xYourAddress",
    "network": "optimism",
    "sourceNetwork": "optimism",
    "grossAmount": "5000000",
    "netAmount": "4900000",
    "settlementTx": "0xeb80…e5a8",
    "fillTx": "0xa91c…44fe",
    "depositTx": "0x8186…1234",
    "refundTx": null,
    "error": null,
    "createdAt": 1783656257928,
    "updatedAt": 1783656258080
  }
  ```
</ResponseExample>