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 — see Getting access.
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. The address is minted under your API key, so MPS must be enabled for it.

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

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: "2000000", // ~2 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,
    swift: true, mctp: true, fastMctp: true, monoChain: true, fullList: true,
    sdkVersion: "15_0_0",
  }),
});

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": "2000000",  # ~2 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,
        "swift": True, "mctp": True, "fastMctp": True, "monoChain": True, "fullList": True,
        "sdkVersion": "15_0_0",
    },
)
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",
      "mpsDepositAddress": "0xafb7e27de13e435a7f1d1a21d33b26edff17bc8b",
      "mpsIntegratorId": "12",
      "mpsUserId": "0x3a1f…",
      "expectedAmountOut": 1.999
    }
  ]
}

Read mpsDepositAddress from any eligible quote (SWIFT, MONO_CHAIN, or a direct FAST_MCTP) — they all share the same address. Quotes that aren’t eligible return mpsDepositAddress: null.

The address is deterministic and permanent for a given recipient + mpsUserId — requesting another quote returns the same address, so it’s safe to call on every checkout. It’s null unless MPS is enabled for your key, 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). MPS 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 SPL / Token-2022 deposits (USDC, USDT, WETH).

Whitelisted tokens — the native coin and USDC on EVM, and USDC / USDT / WETH 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"],
  auth: { 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: "2000000", // ~2 USDC
      fromChain: "arbitrum",
      fromToken: USDC_ARB,
      toChain: "base",
      toToken: USDC_BASE,
      slippageBps: "auto",
      destinationAddress: merchantWallet,
      mpsDeposit: true,
      mpsUserId: orderIdToUserId(orderId),
      swift: true, mctp: true, fastMctp: true, monoChain: true, fullList: true,
      sdkVersion: "15_0_0",
    }),
  });
  const { quotes } = await res.json();
  const depositAddress = quotes.map((q: any) => q.mpsDepositAddress).find(Boolean);
  if (!depositAddress) throw new Error("MPS deposit address unavailable — enable MPS on your key and check the token minimum.");
  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": "2000000",  # ~2 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),
            "swift": True, "mctp": True, "fastMctp": True, "monoChain": True, "fullList": True,
            "sdkVersion": "15_0_0",
        },
    )
    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 ~2 USDC on Arbitrum; the merchant receives USDC on Base, and you get a status_changed → completed event to fulfil the order.

Deposits below the per-chain minimum USD value are detected but not settled. You still receive a deposit_detected event with queued: false and ignoredReason: "below_min", so it’s never a silent gap.

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"], auth: { 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"], auth={"apiKey": 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 ~2 USDC on Base or Solana → receive USDC on Arbitrum) are on the Examples page.

ARCHITECTURE

INTEGRATION

PAYMENT SERVICE

APPLICATION

RESOURCES

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

​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

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