Mexico — MXN on/offramp

Move money between MXN bank accounts (SPEI/CLABE) and the MXN wallet. Onramps are deposit-driven; offramps are a quote plus on-device signatures.

LifecycleUserWalletKYCRailFundMove money

Once a Mexican user has completed Mexico KYC (their CLABE is provisioned automatically during activation), money moves in two directions:

• Onramp: the user sends MXN by SPEI transfer to their own CLABE → MEXe arrives in the smart wallet automatically. No quote or order call is needed.
• Offramp: MEXe → MXN paid out to the user’s registered bank account, via a quote and on-device signatures.

Paying someone else’s Mexican bank account, from a USD or any other wallet, is a different rail: LATAM bank payouts. It needs no Mexico KYC on the sender and does not touch the MXN wallet.

---

Onramp — just deposit

There is no onramp quote. Read the user’s deposit CLABE and show it to them:

GET /v1/users/{userId}/bank-accounts/deposit-accounts/MXN

{
  "accounts": [
    {
      "id": "ba_mx_123",
      "accountName": "Ana García López",
      "bankName": "Fintoc",
      "currency": "MXN",
      "clabe": "646180111812345678",
      "targetCurrency": "MEXe",
      "status": "active"
    }
  ]
}

The account appears only once Mexico KYC is approved, and only status: "active" accounts can receive deposits. The unfiltered GET …/bank-accounts/deposit-accounts returns the same account under its mexicanAccounts group.

When the user sends a SPEI transfer to that CLABE from any bank, an onramp order is created automatically and MEXe is credited to their smart wallet — no further API calls. Track it via order tracking or the wallet balance.

---

Offramp

1. Create a quote

POST /v1/users/{userId}/latam/mx/quote
{
  "type": "offramp",
  "sourceAmount": "1000.00",
  "note": "Payout"
}

Field
type	required — only "offramp" (onramps are deposit-driven and take no quote)
sourceAmount	required — decimal string, e.g. "1000.00"
note	optional free text

The response locks in pricing until expiresAt and already carries the orderId:

{
  "quoteId": "b9fa08b5-46ae-4d85-9ac2-6ca2f4d91234",
  "orderId": "7c21e6d0-1f3a-4b6e-9d2c-5f8a3b7c1234",
  "blockchain": "base",
  "quoteAssets": { "type": "offramp", "sourceAsset": "MEXe", "targetAsset": "MXN" },
  "sourceAmount": "1000.00",
  "destinationAmount": "998.50",
  "feeBps": "15",
  "feeAmount": "1.50",
  "exchangeRate": "1.00",
  "expiresAt": "2026-06-02T12:00:30.000Z",
  "signatureRequest": { "…": "…" }
}

2. Sign the approve request (when present)

signatureRequest is the first (approve) operation, granting the provider allowance to burn the user’s MEXe. Sign and submit it on-device via bmoni_embedded_sdk, the same pattern as other smart-wallet mutations. It is absent when the wallet already has sufficient allowance — skip straight to polling the order.

3. Poll the order for the burn request

GET /v1/users/{userId}/latam/mx/orders/{orderId}

Once the burn calldata is ready the order carries burnSignatureRequest — the second on-device signature authorizing the token burn. Sign and submit it the same way. This step is required whether or not an approve signatureRequest was returned in step 1.

After the burn settles, the MXN payout goes to the user’s registered bank account.

4. Poll for settlement

GET /v1/users/{userId}/wallets/workflows/{workflowId}

Both signatures carry the same workflowId — the offramp is one workflow end to end. isTerminal goes true once the fiat has been paid out or the offramp has failed; see the signature pattern for the response shape. The order (below) carries the provider’s view of the same operation; poll either or both.

---

Track an order

GET /v1/users/{userId}/latam/mx/orders/{orderId}

Field	Notes
status	created → funded → completed, or failed / refunded / canceled
orderType	onramp or offramp
depositClabe, depositClabeName	For onramp: the CLABE the deposit was received on (with a memo reference where present)
statusPage	Provider-hosted page showing live order status
amountInFiat, amountInTokens	Settled amounts once known
burnSignatureRequest	Offramp only — present when the burn signature is needed

---

MXNe → MEXe migration

Users who onboarded before the MXN wallet moved from the CETES-backed MXNe token to MEXe may still hold a legacy MXNe balance. Migrate it 1:1 — no fee, no reserve.

1. Check eligibility

GET /v1/users/{userId}/latam/mx/mxne-migration/status

{
  "eligible": true,
  "mxneBalance": "250.00",
  "walletAddress": "0xabc…"
}

Call this once per session before showing the MXN wallet, and only surface an “upgrade your MXN wallet” prompt when eligible is true. mxneBalance reads "0" when there is nothing to migrate.

2. Prepare the migration

POST /v1/users/{userId}/latam/mx/mxne-migration/prepare

Takes no body. Builds a batched UserOp (approve + executeQuote) that swaps the wallet’s full MXNe balance into MEXe:

{
  "fromStablecoin": "MXNe",
  "toStablecoin": "MEXe",
  "amount": "250.00",
  "signatureRequest": { "…": "…" }
}

Returns 400 if the wallet has no MXNe balance — call mxne-migration/status first and only prepare when eligible is true.

3. Sign and submit

Sign signatureRequest on-device via bmoni_embedded_sdk and submit it the same way as any other smart-wallet mutation:

POST /v1/users/{userId}/wallets/submit-signature
{ "workflowId": "…", "signature": "0x…" }

The swap executes atomically against the liquidity pool. There is no order record, so the workflow is the only place to see it settle:

GET /v1/users/{userId}/wallets/workflows/{workflowId}

Poll until isTerminal is true, then refresh the wallet balance — the MXNe is gone and the same amount of MEXe is in its place.