Quickstart

Before you start

You'll need:

A MexicoP2P partner API key (format: mp2p_xxx) — see Getting Started
A webhook URL on your server (HTTPS) to receive order status updates

Replace mp2p_test_xxx with your actual API key in all examples below.

Step 1: Verify your API key

curl -H "X-API-Key: mp2p_test_xxx" \
  https://mexicop2p.org/api/v1/health

{
  "status": "ok",
  "partner": "Acme Finance",
  "tier": "GROWTH",
  "timestamp": "2025-06-15T12:00:00.000Z"
}

If you get a 401, double-check your key. See error codes for details.

Step 2: Register a user

Create a user record tied to your internal user ID. You only need to do this once per user.

curl -X POST \
  -H "X-API-Key: mp2p_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{"partnerUserRef": "user_12345"}' \
  https://mexicop2p.org/api/v1/users

{
  "id": "cm3abc123",
  "partnerUserRef": "user_12345",
  "kycStatus": "NOT_REQUIRED",
  "kycTier": "NONE",
  "orderCount": 0,
  "totalVolumeMxn": 0,
  "createdAt": "2025-06-15T12:01:00.000Z"
}

partnerUserRef is your internal user ID — use whatever identifier makes sense in your system.

KYC is not required for initial trades. It's triggered automatically when a user's volume exceeds tier thresholds. See KYC models for details.

Step 3: Get a rate and create a quote

First, check the current exchange rate:

curl -H "X-API-Key: mp2p_test_xxx" \
  https://mexicop2p.org/api/v1/exchange-rate

{
  "usdMxn": 17.25,
  "source": "banxico",
  "timestamp": "2025-06-15T12:02:00.000Z",
  "validFor": 300
}

Then lock that rate by creating a quote (valid for 5 minutes). You can optionally set a feePercent — your markup on the trade:

curl -X POST \
  -H "X-API-Key: mp2p_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "SELL",
    "amountUsdc": 100,
    "partnerUserRef": "user_12345",
    "feePercent": 1.5,
    "feeRecipient": "PARTNER"
  }' \
  https://mexicop2p.org/api/v1/quotes

{
  "id": "qt_abc123",
  "type": "SELL",
  "amountUsdc": 100,
  "exchangeRate": 17.25,
  "grossAmountMxn": 1725.00,
  "feePercent": 1.5,
  "feeAmountMxn": 25.88,
  "feeRecipient": "PARTNER",
  "netAmountMxn": 1699.12,
  "expiresAt": "2025-06-15T12:08:00.000Z"
}

MexicoP2P doesn't charge fees to users — feePercent is your optional markup as a partner. If you don't set it, it defaults to 0 and the user gets the raw exchange rate. See Pricing for details.

Step 4: Create an order

Convert the quote into a live escrow order:

curl -X POST \
  -H "X-API-Key: mp2p_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "quoteId": "qt_abc123",
    "partnerUserRef": "user_12345",
    "sellerClabe": "012345678901234567"
  }' \
  https://mexicop2p.org/api/v1/orders

{
  "id": "ord_xyz789",
  "escrowOrderId": "0x1a2b3c...",
  "status": "PENDING_DEPOSIT",
  "token": "USDC",
  "amountUsdc": 100,
  "totalMxn": 1725.00,
  "exchangeRate": 17.25,
  "sellerClabe": "012345678901234567",
  "amlRiskLevel": "LOW",
  "expiresAt": "2025-06-15T13:03:00.000Z",
  "createdAt": "2025-06-15T12:03:00.000Z"
}

sellerClabe is the seller's 18-digit CLABE (Mexican standardized bank account number) where the buyer will send pesos via SPEI.

What happens next — you don't need to do anything

The order starts at PENDING_DEPOSIT. From here, everything is automatic:

Seller deposits crypto into the Starknet escrow contract → status becomes ACTIVE
A buyer on the marketplace locks the order → status becomes LOCKED
Buyer sends MXN via SPEI to the seller's CLABE and provides a CEP (digital payment receipt)
MexicoP2P verifies the CEP with Banxico → status becomes PENDING_RELEASE
Crypto is released to the buyer on-chain → status becomes COMPLETED

You'll receive a webhook at each step. No additional API calls are needed.

Step 5: Track the order

Option A: Webhooks (recommended)

Configure your webhook URL in the Partner Dashboard. You'll receive events like:

{
  "event": "order.completed",
  "data": {
    "orderId": "ord_xyz789",
    "status": "COMPLETED",
    "completedAt": "2025-06-15T14:30:00.000Z"
  },
  "timestamp": "2025-06-15T14:30:01.000Z"
}

See Webhook Overview for all event types and Signature Verification for security.

Option B: Polling

If webhooks aren't set up yet, you can poll the order status:

curl -H "X-API-Key: mp2p_test_xxx" \
  https://mexicop2p.org/api/v1/orders/ord_xyz789

Poll at most once per minute. Prefer webhooks for production.

Complete Node.js example

const API_KEY = "mp2p_test_xxx";
const BASE = "https://mexicop2p.org/api/v1";

const headers = {
  "X-API-Key": API_KEY,
  "Content-Type": "application/json",
};

// 1. Register a user (once)
const user = await fetch(`${BASE}/users`, {
  method: "POST",
  headers,
  body: JSON.stringify({ partnerUserRef: "user_12345" }),
}).then((r) => r.json());

// 2. Create a quote (feePercent is optional — your markup)
const quote = await fetch(`${BASE}/quotes`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    type: "SELL",
    amountUsdc: 100,
    partnerUserRef: "user_12345",
    feePercent: 1.5,
    feeRecipient: "PARTNER",
  }),
}).then((r) => r.json());

// 3. Create an order
const order = await fetch(`${BASE}/orders`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    quoteId: quote.id,
    partnerUserRef: "user_12345",
    sellerClabe: "012345678901234567",
  }),
}).then((r) => r.json());

console.log(`Order ${order.id} created — status: ${order.status}`);
// Now wait for webhooks to track progress

What's next

How It Works — Understand the full trade flow, KYC models, and dispute resolution
API Reference — Complete endpoint documentation
Webhooks — Set up real-time event notifications

On this page