API Reference

Base URL

https://mps-api.mayan.finance

Authentication

Every authenticated request must include your API key (a UUID) in the x-api-key header:

x-api-key: your-uuid-api-key

GET /chains and GET /source-config are public and do not require a key. A missing key returns 401 UNAUTHORIZED; an invalid key returns 403 FORBIDDEN.

Pagination

List endpoints are cursor-paginated by creation time (newest first).

Query param	Description
`limit`	Page size. Default `20`, max `100`.
`cursor`	ISO-8601 timestamp from a previous response’s `nextCursor`.

Each response includes nextCursor; pass it back as cursor for the next page. When nextCursor is null, there are no more pages.

Errors

Error shape

All API errors, plus the error field on a swap and on a status_changed event, share one structured shape:

{
  "code": "VALIDATION_ERROR",
  "message": "Human-readable, safe to surface.",
  "retryable": false,
  "details": { "field": "evm" }
}

API error responses wrap it as { "error": { ... } } with an appropriate HTTP status. Always branch on code (a stable enum) rather than message (which may be reworded). details, when present, holds only safe, parameterized context (numbers, ids, thresholds), never raw internal exception text.

Error codes

Code	Retryable	Meaning
`VALIDATION_ERROR`	no	Bad or missing request parameters
`UNAUTHORIZED`	no	Missing `x-api-key`
`FORBIDDEN`	no	Invalid API key
`UNSUPPORTED_CHAIN`	no	Unknown chain id in the request
`RESOLVE_FAILED`	yes	Could not fetch/decode the transaction (e.g. RPC)
`NOT_CONFIGURED`	no	A server feature is not configured
`NOT_FOUND`	no	Resource does not exist
`INSUFFICIENT_BALANCE`	yes	Relayer/wallet lacked funds to send the tx
`AMOUNT_TOO_SMALL`	yes	Deposit value below what the route/fees allow
`FEE_NOT_COVERED`	yes	Collected fee does not cover settlement cost
`NO_ROUTE`	yes	No quote/route available for this pair right now
`QUOTE_INVALID`	yes	A quote was returned but failed validation
`UNSUPPORTED_ROUTE`	no	This source/destination combination is not supported
`UNSUPPORTED_DEST`	no	Destination chain is not supported
`TX_REVERTED`	yes	An on-chain transaction reverted
`SIMULATION_REVERTED`	yes	Pre-flight simulation reverted
`RPC_UNAVAILABLE`	yes	RPC timeout / connection / rate-limit
`PRICE_UNAVAILABLE`	yes	Token could not be priced
`REORG`	yes	A prior on-chain step was re-orged away
`CONFIG_MISSING`	yes	A required config is missing (recovers once set)
`INTERNAL`	yes	Unclassified failure (message is generic; cause is logged server-side)

On a swap, error.retryable also reflects state: a dead (terminal) item always reports retryable: false, because the worker will not try it again regardless of the code.

Get a deposit address

You don’t call the deposit address service to mint a deposit address. You get one from the Mayan Quote API. Request a quote with mpsDeposit: true and a destinationAddress, then read mpsDepositAddress off any eligible quote. The address is deterministic and permanent for a given recipient, and Mayan settles anything sent to it automatically. See Deposit address on the Quote API for the request/response shape and eligibility rules.

List deposit addresses

Paginated deposit addresses that have been created for the authenticated integrator (each is minted the first time you request a quote with mpsDeposit: true for a new recipient).

GET /deposit-addresses?limit=20&cursor=<ISO timestamp>

Response

{
  "items": [
    {
      "id": "uuid",
      "walletAddress": "0x...",
      "userId": "0x...",
      "destChain": "30",
      "destWallet": "0x...",
      "destToken": "0x...",
      "chainType": "evm",
      "createdAt": "2026-04-03T00:00:00.000Z"
    }
  ],
  "nextCursor": "2026-04-02T23:59:00.000Z"
}

List swaps

Paginated settlement status for your deposit addresses. This is the endpoint to poll for payment progress. Each item is a settlement request: Mayan sweeps the wallet’s balance of tokenAddress on chainId and delivers it to the destination.

GET /swaps?limit=20&cursor=<ISO timestamp>

Response

{
  "items": [
    {
      "id": "uuid",
      "status": "failed_swap",
      "phase": "swap",
      "category": "retrying",
      "terminal": false,
      "chainId": 6,
      "tokenAddress": "0x...",
      "amount": "1000000",
      "swapTxHash": null,
      "error": {
        "code": "RPC_UNAVAILABLE",
        "message": "Upstream RPC is temporarily unavailable.",
        "retryable": true,
        "details": { "reason": "fetch failed" }
      },
      "retryCount": 2,
      "walletAddress": "0x...",
      "userId": "0x...",
      "destChain": "30",
      "destWallet": "0x...",
      "destToken": "0x...",
      "createdAt": "2026-04-03T00:00:00.000Z",
      "updatedAt": "2026-04-03T00:01:00.000Z"
    }
  ],
  "nextCursor": "2026-04-02T23:59:00.000Z"
}

chainId is the Wormhole chain ID the funds are on; tokenAddress is the token being settled.
amount is a best-effort snapshot for display (raw smallest-unit string, or null for a request-indexed settlement). The actual settled amount is the wallet’s live balance at swap time.
error is null unless the item is failing/deferred. A non-null error never means success.
See Swap Statuses for status/phase/category/terminal, and swapTxHash for the settlement transaction (view it on Mayan Explorer).

Request index

Trigger settlement for a token the scanner doesn’t auto-detect. Only whitelisted tokens (native + USDC on EVM; SOL/USDC/USDT/WETH/WSOL on Solana) are detected automatically. For any other token, call this with one of your deposit addresses (an mpsDepositAddress from a quote), the token, and the chain. Mayan queues a settlement and the worker sweeps the wallet’s live balance. If a settlement for that wallet+token is already active, the call is deduped.

POST /request-index

Request body

Field	Type	Description
`walletAddress`	string	one of your deposit addresses (an `mpsDepositAddress` from a quote)
`tokenAddress`	string	the token to index: a contract/mint address, or `"native"` for the gas token
`chain`	number	the Wormhole chain ID the wallet holds the token on

Example

curl -X POST https://mps-api.mayan.finance/request-index \
  -H "Content-Type: application/json" \
  -H "x-api-key: $MAYAN_API_KEY" \
  -d '{
    "walletAddress": "0xff129358605c18388f527d97dbf20e30ea6ddaea",
    "tokenAddress": "0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7",
    "chain": 6
  }'

Response

{
  "chainId": 6,
  "walletAddress": "0xff129358605c18388f527d97dbf20e30ea6ddaea",
  "tokenAddress": "0xb31f66aa3c1e785363f0875a1b74e27b85fd66c7",
  "queued": true,
  "queueItemId": "uuid",
  "reason": null
}

queueItemId is the settlement id (null when not queued). Track it via GET /swaps and status_changed events.
When queued is false, reason explains why: "already_queued" (a settlement for this wallet+token is already active; the in-flight one will sweep the new balance too), "below_token_min" (below the token’s configured minimum), or "below_min" (below the chain’s USD floor).
Returns 404 NOT_FOUND if walletAddress is not one of your registered deposit addresses.

Chain info

Supported chains with their block-explorer URLs. No authentication required.

GET /chains

Response

[
  { "chainId": 6, "name": "avalanche", "explorerTxUrl": "https://snowtrace.io/tx/", "kind": "evm" },
  { "chainId": 1, "name": "solana", "explorerTxUrl": "https://solscan.io/tx/", "kind": "svm" }
]

kind is "evm" or "svm". This lists every chain (as a destination or explorer target); to discover which source chains and tokens the scanner actually detects and settles, use GET /source-config.

Source config

The source chains and tokens the scanner auto-detects and settles, with the minimum deposit advertised per token. No authentication required. Poll this instead of hardcoding a list. The minimums here are the same ones the deposit gate enforces, so they never drift. Any token not listed can still be settled on demand via POST /request-index.

GET /source-config

Response

{
  "chains": [
    {
      "chainId": 30,
      "name": "base",
      "kind": "evm",
      "tokens": [
        { "address": "0x0000000000000000000000000000000000000000", "symbol": "BASE", "standard": "native", "minDeposit": "0.002", "decimals": 18 },
        { "address": "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "symbol": "USDC", "standard": "erc20", "minDeposit": "3", "decimals": 6 }
      ]
    },
    {
      "chainId": 1,
      "name": "solana",
      "kind": "svm",
      "tokens": [
        { "address": "11111111111111111111111111111111", "symbol": "SOL", "standard": "native", "minDeposit": "0.02", "decimals": 9 },
        { "address": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", "symbol": "USDC", "standard": "spl", "minDeposit": "3", "decimals": 6 },
        { "address": "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB", "symbol": "USDT", "standard": "spl", "minDeposit": "3", "decimals": 6 },
        { "address": "7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs", "symbol": "WETH", "standard": "spl", "minDeposit": "0.002", "decimals": 8 },
        { "address": "So11111111111111111111111111111111111111112", "symbol": "WSOL", "standard": "spl", "minDeposit": "0.02", "decimals": 9 }
      ]
    }
  ]
}

Field	Type	Description
`chains[].chainId`	number	Source Wormhole chain ID
`chains[].name`	string	Chain name
`chains[].kind`	string	`"evm"` or `"svm"`
`chains[].tokens[].address`	string	Contract/mint address. The native coin uses that chain’s zero/default address: `0x0000…0000` on EVM, the system program `1111…1111` on Solana
`chains[].tokens[].symbol`	string?	Token symbol, when known (each EVM native coin’s symbol is the chain name uppercased; Solana’s native coin is `SOL`)
`chains[].tokens[].standard`	string	`"native"`, `"erc20"`, or `"spl"`
`chains[].tokens[].minDeposit`	string?	Minimum deposit in the token’s own units (human-readable, e.g. `"10"` USDC). Present only when a minimum is configured.
`chains[].tokens[].decimals`	number?	Token decimals, paired with `minDeposit` to convert an on-chain (base-unit) balance for comparison.

SOL vs. WSOL on Solana. Both are auto-detected, as two separate entries pointing at two different balances. SOL (standard: "native", address 1111…1111) is native lamports sent to the vault address with a plain system transfer. WSOL (standard: "spl", address So1111…1112) is the wrapped-SOL SPL token held in the vault’s token account. Match the entry to what you actually send, and pass that same address to POST /request-index if you ever need to trigger one manually.

A deposit below the advertised minimum is detected but not settled. You still get a deposit_detected event with queued: false and ignoredReason: "below_token_min" (or "below_min" for the chain-level USD floor). See deposit_detected.

Event replay

Fetch this integrator’s events in chronological order, used to catch up after a WebSocket disconnect. Events are retained for 30 days.

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

Query param	Description
`since`	Return events created strictly after this timestamp. Omit to start from the oldest retained event.
`type`	Optional filter: `deposit_detected` or `status_changed`.
`limit`	Page size. Default `50`, max `200`.

Response (ascending by time):

{
  "items": [
    { "id": "uuid", "type": "status_changed", "data": { "...": "..." }, "timestamp": "2026-04-03T00:00:00.000Z" }
  ],
  "nextCursor": "2026-04-03T00:00:00.000Z"
}

Page forward with nextCursor until it is null. See Delivery & replay for the full pattern.

GET STARTED

USE CASES

SOLUTIONS

HOW MAYAN WORKS

FEATURES

INTEGRATION

RESOURCES

AI AGENTS

API Reference

Base URL

Authentication

Errors

Error shape

Error codes

Get a deposit address

List deposit addresses

List swaps

Request index

Chain info

Source config

Event replay

​Base URL

​Authentication

​Pagination

​Errors

​Error shape

​Error codes

​Get a deposit address

​List deposit addresses

​List swaps

​Request index

​Chain info

​Source config

​Event replay

Base URL

Authentication

Pagination

Errors

Error shape

Error codes

Get a deposit address

List deposit addresses

List swaps

Request index

Chain info

Source config

Event replay