Overview

​

Base URL

https://api-antseed.mrdn.finance

​

Endpoints

​

How it works

1. Send POST /v1/antseed/topups with a buyer and no payment. The 402 Payment Required response contains one entry per eligible source in accepts[] and source bounds in topup.sources[]. If amount is omitted, the gateway uses the buyer’s full headroom.
2. Choose a source and sign an EIP-3009 TransferWithAuthorization using its chain id and token domain. If the payer differs from buyer, derive the authorization nonce from a payer-commitment-v1 beneficiary binding. Cross-chain entries include 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. Payments from sources other than Base 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

​

Trust assumptions

• Signed payment. The EIP-3009 authorization fixes the token, amount, facilitator, validity window, payer, and nonce. For a third-party top-up, the nonce is a commitment to the merchant, source and destination details, credited recipient, payer, and buyer. A captured payment cannot be redirected to another buyer.
• Facilitator contract. Payments pass through the verified X402ProxyFacilitator contract.
• Relayer. The merchant relayer holds the settled funds until it completes the merchant deposit or refunds the payer. Its transactions and the final credited amount are recorded in the top-up status.
• Cross-chain payments. Payments from other chains use Across to deliver funds to Base before merchant fulfillment.

​

Rules worth knowing

• Payer and buyer may differ. A third-party top-up must include a valid payer-commitment-v1 beneficiary binding. The official @meridian/topup-client package creates it automatically while keeping the flow to one wallet signature. Without a binding, a different buyer is rejected (buyer_mismatch).
• Fees. The merchant receives the amount delivered on Base after Meridian and Across fees. Responses show grossAmount and netAmount in 6-decimal base units.
• Idempotent. Replaying the same X-PAYMENT returns the existing top-up. Each EIP-3009 authorization (payer, nonce) is accepted exactly once.
• Pending requests. A 503 means the payment is still being reconciled. Retry with the same X-PAYMENT or poll its topupId.
• Ethereum gas protection. Ethereum settlement is not broadcast when its estimated L1 gas cost exceeds the facilitator fee or when the gas-price inputs are unavailable. The gateway returns 503; retry after the supplied Retry-After interval with the same payment.
• 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.

​

Recommended integration

await topupClient.topup({
  buyer: antseedBuyerAddress,
  amount: "5",
  network: "optimism",
  signer: connectedWallet,
});