Payments Quickstart

This guide takes you from zero to a working cross-chain payment: get a deposit address from a quote, let a user deposit, and get notified when funds are delivered.

Prerequisites

An API key (UUID) from the Mayan team. Email support@mayan.finance to get one. No key yet? Try the public demo key 03b9969f-7c6a-4bd1-9ad4-c0e0e9f3dcb7 (shared, for evaluation only). You need a key for the MPS panel and for the tracking endpoints below. Pass the same key when you request the quote, because the deposit address is tied to it and only that key can track its payments.
The base URL: https://mps-api.mayan.finance.

All authenticated requests send your key in the x-api-key header.

1. Get a deposit address from a quote

Request a Mayan quote with mpsDeposit: true and a destinationAddress (where the funds settle), then read mpsDepositAddress from an eligible quote. It’s a deterministic address on the quote’s source chain. In the example below the payer funds on Arbitrum and the merchant receives USDC on Base. Send your API key with this call, so the address is created under your integrator.

curl -X POST "https://price-api.mayan.finance/v3/quote?apiKey=$MAYAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amountIn64": "5000000",
    "fromChain": "arbitrum",
    "fromToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
    "toChain": "base",
    "toToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
    "slippageBps": "auto",
    "destinationAddress": "0xEab4Fb2De5a05Ba392eB2614bd2293592d455A4f",
    "mpsDeposit": true,
    "solanaProgram": "FC4eXxkyrMPTjiYUpp4EAnkmwMbQyZ6NDCh1kfLn6vsf",
    "forwarderAddress": "0x337685fdaB40D39bd02028545a4FfA7D287cC3E2",
    "swift": true, "mctp": true, "fastMctp": true, "monoChain": true, "fullList": true,
    "sdkVersion": "15_2_2"
  }'

const PRICE_URL = "https://price-api.mayan.finance";
const API_KEY = process.env.MAYAN_API_KEY!;

const res = await fetch(`${PRICE_URL}/v3/quote?apiKey=${API_KEY}`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    amountIn64: "5000000", // ~5 USDC (6 decimals)
    fromChain: "arbitrum",
    fromToken: "0xaf88d065e77c8cC2239327C5EDb3A432268e5831", // USDC on Arbitrum (source)
    toChain: "base",
    toToken: "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", // USDC on Base (destination)
    slippageBps: "auto",
    destinationAddress: "0xEab4Fb2De5a05Ba392eB2614bd2293592d455A4f",
    mpsDeposit: true,
    solanaProgram: "FC4eXxkyrMPTjiYUpp4EAnkmwMbQyZ6NDCh1kfLn6vsf",
    forwarderAddress: "0x337685fdaB40D39bd02028545a4FfA7D287cC3E2",
    swift: true, mctp: true, fastMctp: true, monoChain: true, fullList: true,
    sdkVersion: "15_2_2",
  }),
});

const { quotes } = await res.json();
// All eligible quotes carry the same address; take the first non-null one.
const depositAddress = quotes.map((q) => q.mpsDepositAddress).find(Boolean);
console.log(depositAddress); // address on Arbitrum (the source chain)

import os, requests

PRICE_URL = "https://price-api.mayan.finance"
API_KEY = os.environ["MAYAN_API_KEY"]

res = requests.post(
    f"{PRICE_URL}/v3/quote",
    params={"apiKey": API_KEY},
    json={
        "amountIn64": "5000000",  # ~5 USDC (6 decimals)
        "fromChain": "arbitrum",
        "fromToken": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",  # USDC on Arbitrum (source)
        "toChain": "base",
        "toToken": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",  # USDC on Base (destination)
        "slippageBps": "auto",
        "destinationAddress": "0xEab4Fb2De5a05Ba392eB2614bd2293592d455A4f",
        "mpsDeposit": True,
        "solanaProgram": "FC4eXxkyrMPTjiYUpp4EAnkmwMbQyZ6NDCh1kfLn6vsf",
        "forwarderAddress": "0x337685fdaB40D39bd02028545a4FfA7D287cC3E2",
        "swift": True, "mctp": True, "fastMctp": True, "monoChain": True, "fullList": True,
        "sdkVersion": "15_2_2",
    },
)
quotes = res.json()["quotes"]
deposit_address = next((q["mpsDepositAddress"] for q in quotes if q.get("mpsDepositAddress")), None)
print(deposit_address)  # address on Arbitrum (the source chain)

Response (abridged, one quote shown):

{
  "quotes": [
    {
      "type": "SWIFT",
      "effectiveAmountIn64": "5000000",
      "swapRelayerFee64": "149700",
      "mpsDepositAddress": "0xafb7e27de13e435a7f1d1a21d33b26edff17bc8b",
      "mpsIntegratorId": "12",
      "mpsUserId": "0x3a1f…",
      "expectedAmountOut": 4.849
    }
  ]
}

When a deposit address is offered, every quote in the response is a SWIFT or MONO_CHAIN route and carries the same mpsDepositAddress. The quotes are already priced for the deposit minus Mayan’s settlement cost: effectiveAmountIn64 is what the user sends, swapRelayerFee64 is that cost in source-token base units, and expectedAmountOut is what the merchant receives.

The address is deterministic and permanent for the same API key, mpsUserId, recipient, destination chain and destination token. Requesting another quote returns the same address, so it’s safe to call on every checkout. It’s only returned when destinationAddress is set and the amount clears the token’s minimum.

2. Let the user deposit

Show mpsDepositAddress to your user and have them send the input token on the source chain (Arbitrum, in the example above). Mayan detects the deposit and settles it to your destination token automatically. No signature, no transaction to build.

A quote from an EVM source chain returns an EVM address (valid on that chain).
A quote from Solana returns a Solana vault for native SOL and SPL / Token-2022 deposits (SOL, USDC, USDT, WETH, WSOL).

Whitelisted tokens (the native coin and USDC on EVM, and SOL / USDC / USDT / WETH / WSOL on Solana) are detected automatically. For any other token, trigger indexing yourself with POST /request-index. See Supported tokens.

3. Receive the settlement

You have two ways to track a payment. Use whichever fits your stack:

WebSocket (real-time)
Polling

The stream is served over Socket.IO (bun add socket.io-client). Connect and receive deposit_detected and status_changed events as they happen.

import * as io from "socket.io-client";

const socket = io.connect("https://mps-api.mayan.finance", {
  transports: ["websocket"],
  query: { apiKey: API_KEY },
});

socket.on("event", (evt) => {
  if (evt.type === "status_changed" && evt.data.terminal) {
    // completed = success, dead = gave up
    console.log(evt.data.status, evt.data.queueItemId, evt.data.txHash);
  }
});

See Events for the full payloads and reconnection/replay guidance.

Poll GET /swaps and read each item’s status, terminal, and error. A payment is delivered when status is completed.

curl "https://mps-api.mayan.finance/swaps?limit=20" -H "x-api-key: $MAYAN_API_KEY"

A payment is done when a swap reaches status: "completed" (terminal: true, category: "success"). Most transfers settle in seconds. See Swap Statuses for the full lifecycle.

Full example: e-commerce checkout

Map your order ID to a stable mpsUserId so the same order always maps to the same deposit address, then watch for the terminal event.

import { createHash } from "node:crypto";

const PRICE_URL = "https://price-api.mayan.finance";
const API_KEY = process.env.MAYAN_API_KEY!;
const USDC_ARB = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"; // payer deposits USDC on Arbitrum
const USDC_BASE = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"; // merchant receives USDC on Base

// Map any order id to a stable 20-byte mpsUserId (sha256 → first 20 bytes).
const orderIdToUserId = (orderId: string) =>
  "0x" + createHash("sha256").update(orderId).digest("hex").slice(0, 40);

export async function createPaymentAddress(orderId: string, merchantWallet: string) {
  const res = await fetch(`${PRICE_URL}/v3/quote?apiKey=${API_KEY}`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      amountIn64: "5000000", // ~5 USDC
      fromChain: "arbitrum",
      fromToken: USDC_ARB,
      toChain: "base",
      toToken: USDC_BASE,
      slippageBps: "auto",
      destinationAddress: merchantWallet,
      mpsDeposit: true,
      mpsUserId: orderIdToUserId(orderId),
      solanaProgram: "FC4eXxkyrMPTjiYUpp4EAnkmwMbQyZ6NDCh1kfLn6vsf",
      forwarderAddress: "0x337685fdaB40D39bd02028545a4FfA7D287cC3E2",
      swift: true, mctp: true, fastMctp: true, monoChain: true, fullList: true,
      sdkVersion: "15_2_2",
    }),
  });
  const { quotes } = await res.json();
  const depositAddress = quotes.map((q: any) => q.mpsDepositAddress).find(Boolean);
  if (!depositAddress) throw new Error("MPS deposit address unavailable: is the amount above the token's minimum deposit?");
  return { depositAddress };
}

import os, hashlib, requests

PRICE_URL = "https://price-api.mayan.finance"
API_KEY = os.environ["MAYAN_API_KEY"]
USDC_ARB = "0xaf88d065e77c8cC2239327C5EDb3A432268e5831"   # payer deposits USDC on Arbitrum
USDC_BASE = "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913"  # merchant receives USDC on Base

# Map any order id to a stable 20-byte mpsUserId (sha256 → first 20 bytes).
def order_id_to_user_id(order_id: str) -> str:
    return "0x" + hashlib.sha256(order_id.encode()).hexdigest()[:40]

def create_payment_address(order_id: str, merchant_wallet: str):
    res = requests.post(
        f"{PRICE_URL}/v3/quote",
        params={"apiKey": API_KEY},
        json={
            "amountIn64": "5000000",  # ~5 USDC
            "fromChain": "arbitrum",
            "fromToken": USDC_ARB,
            "toChain": "base",
            "toToken": USDC_BASE,
            "slippageBps": "auto",
            "destinationAddress": merchant_wallet,
            "mpsDeposit": True,
            "mpsUserId": order_id_to_user_id(order_id),
            "solanaProgram": "FC4eXxkyrMPTjiYUpp4EAnkmwMbQyZ6NDCh1kfLn6vsf",
            "forwarderAddress": "0x337685fdaB40D39bd02028545a4FfA7D287cC3E2",
            "swift": True, "mctp": True, "fastMctp": True, "monoChain": True, "fullList": True,
            "sdkVersion": "15_2_2",
        },
    )
    quotes = res.json()["quotes"]
    deposit_address = next((q["mpsDepositAddress"] for q in quotes if q.get("mpsDepositAddress")), None)
    if not deposit_address:
        raise RuntimeError("MPS deposit address unavailable")
    return {"depositAddress": deposit_address}

Show the deposit address to the customer. They send ~5 USDC on Arbitrum; the merchant receives USDC on Base, and you get a status_changed → completed event to fulfil the order.

Deposits below the token’s minimum are detected but not settled yet. You still receive a deposit_detected event with queued: false and ignoredReason: "below_token_min" (or "below_min"), so it’s never a silent gap. The funds stay in the address and are settled with the next deposit once the total clears the minimum.

Watch a payment end-to-end

Get an address from a quote (step 1), then subscribe to the event stream (Socket.IO) and wait until the settlement is terminal. This is the snippet most integrations start from. It prints each event and resolves on completed (success) or dead (gave up).

import * as io from "socket.io-client"; // bun add socket.io-client

const MPS_URL = "https://mps-api.mayan.finance";
const API_KEY = process.env.MAYAN_API_KEY!;

function watchSettlement(walletAddress: string) {
  const target = walletAddress.toLowerCase();
  return new Promise<{ status: string; txHash: string | null }>((resolve) => {
    const socket = io.connect(MPS_URL, { transports: ["websocket"], query: { apiKey: API_KEY } });
    socket.on("event", (evt) => {
      if (evt.type === "deposit_detected") console.log("deposit detected, queued:", evt.data.queued);
      if (evt.type === "status_changed" && evt.data.walletAddress.toLowerCase() === target) {
        console.log("→", evt.data.status, evt.data.error?.code ?? "");
        if (evt.data.terminal) {
          socket.disconnect();
          resolve({ status: evt.data.status, txHash: evt.data.txHash });
        }
      }
    });
  });
}

// const { depositAddress } = await createPaymentAddress(orderId, merchantWallet); // from the checkout example
const result = await watchSettlement(depositAddress);
console.log(result.status === "completed" ? `✅ delivered: ${result.txHash}` : `❌ ${result.status}`);

# pip install "python-socketio[client]"
import os, socketio

MPS_URL = "https://mps-api.mayan.finance"
API_KEY = os.environ["MAYAN_API_KEY"]

def watch_settlement(wallet_address: str):
    target = wallet_address.lower()
    sio = socketio.Client()
    result = {}

    @sio.on("event")
    def on_event(evt):
        if evt["type"] == "deposit_detected":
            print("deposit detected, queued:", evt["data"]["queued"])
        if evt["type"] == "status_changed" and evt["data"]["walletAddress"].lower() == target:
            print("→", evt["data"]["status"], (evt["data"].get("error") or {}).get("code", ""))
            if evt["data"]["terminal"]:
                result.update(status=evt["data"]["status"], txHash=evt["data"].get("txHash"))
                sio.disconnect()

    sio.connect(MPS_URL, transports=["websocket"], headers={"x-api-key": API_KEY})
    sio.wait()
    return result

# deposit_address = create_payment_address(order_id, merchant_wallet)["depositAddress"]  # from checkout
result = watch_settlement(deposit_address)
print("✅" if result["status"] == "completed" else "❌", result["status"], result.get("txHash"))

Full runnable examples (deposit ~5 USDC on Base or Solana → receive USDC on Arbitrum) are on the Examples page.

GET STARTED

USE CASES

SOLUTIONS

HOW MAYAN WORKS

FEATURES

INTEGRATION

RESOURCES

AI AGENTS

Payments Quickstart

Prerequisites

1. Get a deposit address from a quote

2. Let the user deposit

3. Receive the settlement

Full example: e-commerce checkout

Watch a payment end-to-end

Next steps

Swap Statuses

API Reference

​Prerequisites

​1. Get a deposit address from a quote

​2. Let the user deposit

​3. Receive the settlement

​Full example: e-commerce checkout

​Watch a payment end-to-end

​Next steps

Swap Statuses

API Reference

Prerequisites

1. Get a deposit address from a quote

2. Let the user deposit

3. Receive the settlement

Full example: e-commerce checkout

Watch a payment end-to-end

Next steps