Create Top-up

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

curl -X POST https://api-antseed.mrdn.finance/v1/antseed/topups \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64 signed payment>" \
  -d '{ "buyer": "0xBuyerB", "amount": "5000000", "beneficiary": { "kind": "payer-commitment-v1", "salt": "0x…32 bytes" } }'

{
  "x402Version": 1,
  "error": "X-PAYMENT header required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x…facilitator",
      "maxAmountRequired": "5000000",
      "resource": "https://api-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": "0xBuyerB",
  "payer": "0xPayerA",
  "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
}

POST

{merchant}

topups

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

curl -X POST https://api-antseed.mrdn.finance/v1/antseed/topups \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64 signed payment>" \
  -d '{ "buyer": "0xBuyerB", "amount": "5000000", "beneficiary": { "kind": "payer-commitment-v1", "salt": "0x…32 bytes" } }'

{
  "x402Version": 1,
  "error": "X-PAYMENT header required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x…facilitator",
      "maxAmountRequired": "5000000",
      "resource": "https://api-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": "0xBuyerB",
  "payer": "0xPayerA",
  "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

string

default:"antseed"

required

Merchant id. Currently antseed. Unsupported merchant paths return 404.

Headers

string

required

Must be application/json.

string

Base64-encoded signed x402 payment payload. Omit on the first request to receive the payment requirements via a 402 response.

Body

string

Address to credit on the merchant contract. Required on an unpaid request; on a paid request it defaults to the payment signer. It may differ from authorization.from when the paid request includes a valid beneficiary binding.

string

Gross payment-token amount in 6-decimal base units (for example, "5000000" = 5 tokens). When omitted, the gateway uses the buyer’s maximum available headroom. When paying, it must match authorization.value and be within the bounds returned by the challenge or quote endpoint.

object

Signed x402 payment payload as JSON. Use either this field or the base64-encoded X-PAYMENT header.

object

Required when the payment signer (payer A) differs from buyer (buyer B). The preferred shape is { "kind": "payer-commitment-v1", "salt": "0x…32 bytes" }; the signed EIP-3009 nonce must be the corresponding commitment. Use @meridian/topup-client to construct this automatically.

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`	Payment challenge or clean settlement failure. A clean failure can be retried with the same valid payment. The response also contains a fresh challenge.
`400`	Rejected before settlement: `invalid_request`, `buyer_mismatch`, `invalid_beneficiary`, `beneficiary_expired`, `wrong_network`, `wrong_recipient`, `invalid_signature`, `authorization_not_yet_valid`, `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, bridging, deposit, or refund is pending. Poll the returned `topupId` or retry with the same `X-PAYMENT` after `Retry-After` seconds.
`500`	`needs_review` — an inconsistent, expired, or timed-out bridge state that requires operator attention.

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

curl -X POST https://api-antseed.mrdn.finance/v1/antseed/topups \
  -H "Content-Type: application/json" \
  -H "X-PAYMENT: <base64 signed payment>" \
  -d '{ "buyer": "0xBuyerB", "amount": "5000000", "beneficiary": { "kind": "payer-commitment-v1", "salt": "0x…32 bytes" } }'

The challenge below abbreviates the enabled source list for readability. The live response contains one accepts[] and topup.sources[] entry per source that can accept the requested amount.

{
  "x402Version": 1,
  "error": "X-PAYMENT header required",
  "accepts": [
    {
      "scheme": "exact",
      "network": "base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x…facilitator",
      "maxAmountRequired": "5000000",
      "resource": "https://api-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": "0xBuyerB",
  "payer": "0xPayerA",
  "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
}

Overview

x402 Payments

x402 Inference

Merchant Top-ups

Nanopayments Gateway

Path

Headers

Body

Responses

​Path

​Headers

​Body

​Responses

Path

Headers

Body

Responses