# MexicoP2P Partner API

> Crypto-to-peso infrastructure API. Partners integrate USDC/USDT-to-MXN
> offramp via Starknet escrow + SPEI bank transfers.

Base URL: https://mexicop2p.org/api/v1
Auth: X-API-Key header (format: mp2p_xxx)
Errors: {"error": "CODE", "message": "..."}
Order flow: PENDING_DEPOSIT → ACTIVE → LOCKED → PENDING_RELEASE → COMPLETED

## Endpoints
- Health: GET /health → {status, partner, tier, timestamp}
- Exchange Rate: GET /exchange-rate → {usdMxn, source, timestamp, validFor}
- Quote: POST /quotes {type:"SELL", amountUsdc, partnerUserRef} → {id, exchangeRate, netAmountMxn, expiresAt}
- Create Order: POST /orders {quoteId, partnerUserRef, sellerClabe} → {id, status, amountUsdc, totalMxn}
- List Orders: GET /orders?status=&limit=&offset= → {orders[], total, hasMore}
- Order Detail: GET /orders/:id → {spread, timeline, escrowStatus, ...}
- Register User: POST /users {partnerUserRef} → {id, kycStatus, orderCount}
- Get User: GET /users/:ref → {kycStatus, totalVolumeMxn, amlRiskLevel}
- Start KYC: POST /users/:ref/kyc {level, returnUrl} → {sessionId, sessionUrl}
- Webhook History: GET /webhooks → {deliveries[], total, hasMore}

## Webhooks
Events: order.created, order.deposit_confirmed, order.locked, order.payment_verified,
        order.completed, order.refunded, order.lock_expired, order.disputed, order.dispute_resolved
Signature: HMAC-SHA256("{timestamp}.{payload}", webhookSecret)
Header: X-Webhook-Signature
Retry: 5 attempts, backoff [30s, 2m, 10m, 30m, 2h]

## Rate Limits
FREE tier: 50 req/min, 10 users, 50K MXN/month
GROWTH tier: 200 req/min, 500 users, 1M MXN/month
ENTERPRISE tier: 1000 req/min, unlimited users, custom volume

## Error Codes
MISSING_API_KEY, INVALID_API_KEY, PARTNER_INACTIVE, PARTNER_SUSPENDED,
IP_NOT_ALLOWED, RATE_LIMITED, VALIDATION_ERROR, NOT_FOUND, INVALID_CLABE,
INVALID_QUOTE, QUOTE_EXPIRED, QUOTE_USED, QUOTE_USER_MISMATCH,
DUPLICATE_USER, USER_LIMIT_REACHED, VOLUME_LIMIT_EXCEEDED, KYC_NOT_AVAILABLE,
KYC_LIMIT_REACHED, KYC_SESSION_FAILED

## Optional details
- [Full API documentation](https://docs.mexicop2p.org/llms-full.txt)