Events

MPS emits two event types across its whole lifecycle. Consume them live over Socket.IO, and catch up on anything missed after a disconnect with the GET /events replay endpoint.

Event types

Type	Trigger
`deposit_detected`	A deposit was observed on-chain (fires whether or not it gets queued)
`status_changed`	A swap moved between statuses — covers deploy/swap/settle progress, every retry, deferrals, success, and terminal failure

status_changed is the single lifecycle signal: a completed payment is status_changed with status: "completed", and a freshly deployed wallet rides on the status_changed into pending_swap (carrying its deploy txHash).

Socket.IO

The live stream is served over Socket.IO (bun add socket.io-client). Connect to the base URL and pass your API key in the handshake auth:

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

const socket = io.connect("https://mps-api.mayan.finance", {
  transports: ["websocket"],
  auth: { apiKey: process.env.MAYAN_API_KEY }, // or query: { apiKey } for browser clients
});

socket.on("connect", () => console.log("connected"));
socket.on("connected", ({ integratorName }) => console.log("hello", integratorName));

// Every event arrives on the "event" channel as { type, data, timestamp }.
socket.on("event", (evt) => {
  if (evt.type === "status_changed" && evt.data.terminal) {
    console.log(evt.data.status, evt.data.queueItemId, evt.data.txHash);
  }
});

On a successful connection the server emits a connected event with your integrator name:

{ "integratorName": "your-name" }

Socket.IO keeps the connection alive with its own heartbeat and auto-reconnects on a drop, so you don’t manage pings yourself. Fan-out is still best-effort — after a reconnect, catch up on anything missed via GET /events.

deposit_detected

{
  "type": "deposit_detected",
  "data": {
    "walletAddress": "0x...",
    "chainId": 6,
    "tokenAddress": "0x...",
    "queued": false,
    "ignoredReason": "below_min"
  },
  "timestamp": "2026-04-03T00:00:00.000Z"
}

queued tells you whether the deposit entered the settlement queue. If false, ignoredReason explains why (below_token_min, below_min, no_adapter, enqueue_error) — so a dust/spam deposit that will never produce a swap is an explicit signal, not a detection with no follow-up. below_token_min is the per-token minimum (see GET /source-config); below_min is the chain-level USD floor.

status_changed

{
  "type": "status_changed",
  "data": {
    "queueItemId": "uuid",
    "chainId": 6,
    "tokenAddress": "0x...",
    "walletAddress": "0x...",
    "status": "failed_swap",
    "prevStatus": "swapping",
    "phase": "swap",
    "category": "retrying",
    "terminal": false,
    "retryCount": 2,
    "txHash": null,
    "error": {
      "code": "RPC_UNAVAILABLE",
      "message": "Upstream RPC is temporarily unavailable.",
      "retryable": true,
      "details": { "reason": "fetch failed" }
    }
  },
  "timestamp": "2026-04-03T00:00:00.000Z"
}

queueItemId is the settlement id (matches GET /swaps id).
error is null except on failing/deferred states (see the error model).
txHash carries the wallet-deployment tx on the transition into pending_swap, and the swap/settle tx on the transition into completed.
To react only to final outcomes, filter on terminal: true (completed = success, dead = failure).

Delivery and replay

Socket.IO fan-out is live and best-effort: events are pushed only to currently-connected sockets and are not buffered per connection. Socket.IO auto-reconnects, but events that fired while you were disconnected are not resent — catch up with the replay endpoint rather than relying on the socket.

GET /events?since=<ISO timestamp>&limit=50&type=status_changed

Returns your events in chronological (ascending) order strictly after since (omit since to start from the oldest retained event). Page forward with nextCursor until it is null.

async function drain(sinceISO?: string) {
  let cursor = sinceISO;
  while (true) {
    const url = new URL("https://mps-api.mayan.finance/events");
    url.searchParams.set("limit", "200");
    if (cursor) url.searchParams.set("since", cursor);
    const { items, nextCursor } = await fetch(url, {
      headers: { "x-api-key": process.env.MAYAN_API_KEY! },
    }).then((r) => r.json());

    for (const evt of items) handleEvent(evt);
    if (!nextCursor) break;
    cursor = nextCursor;
  }
}

import os, requests

def drain(since_iso: str | None = None):
    cursor = since_iso
    while True:
        params = {"limit": 200}
        if cursor:
            params["since"] = cursor
        data = requests.get(
            "https://mps-api.mayan.finance/events",
            headers={"x-api-key": os.environ["MAYAN_API_KEY"]},
            params=params,
        ).json()
        for evt in data["items"]:
            handle_event(evt)
        if not data["nextCursor"]:
            break
        cursor = data["nextCursor"]

Events are retained for 30 days and pruned afterwards, so replay only reaches back over the retention window. Treat events as idempotent — dedupe on the event id (from GET /events), or on data.queueItemId + data.status.

ARCHITECTURE

INTEGRATION

PAYMENT SERVICE

APPLICATION

RESOURCES

Event types

Socket.IO

deposit_detected

status_changed

Delivery and replay

​Event types

​Socket.IO

​deposit_detected

​status_changed

​Delivery and replay

Event types

Socket.IO

deposit_detected

status_changed

Delivery and replay