Skip to main content
POST
/
v1
/
{merchant}
/
topups
curl -X POST https://antseed.mrdn.finance/v1/antseed/topups \
  -H "Content-Type: application/json" \
  -d '{ "buyer": "0xYourAddress", "amount": "5000000" }'

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" }'

{
  "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" }
    ]
  }
}

{
  "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
}
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

​
merchant
string
required
Merchant id. Currently antseed. Unknown merchants return 404 unknown_merchant.

​
Headers

​
Content-Type
string
required
Must be application/json.
​
X-PAYMENT
string
Base64-encoded signed x402 payment payload. Omit on the first request to receive the payment requirements via a 402 response.

​
Body

​
buyer
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.
​
amount
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.

​
Responses

StatusMeaning
200Deposited. 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.
402No/invalid payment (fresh multi-source challenge in accepts[] + topup.sources[] bounds), or settlement failed (fresh challenge — retry with a new payment).
400Rejected before settlement: buyer_mismatch, wrong_network, wrong_recipient, invalid_signature, authorization_expired, amount_mismatch, amount_too_low, amount_too_high, … (errorReason names the cause).
409authorization_reused (payment already used), credit_limit_reached, or deposit_failed (deposit impossible after settlement — the settled amount was refunded, see refundTx).
503Settlement 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.
500needs_review — an inconsistent, expired, or timed-out bridge state that requires operator attention.
curl -X POST https://antseed.mrdn.finance/v1/antseed/topups \
  -H "Content-Type: application/json" \
  -d '{ "buyer": "0xYourAddress", "amount": "5000000" }'

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" }'

{
  "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" }
    ]
  }
}

{
  "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
}