Getting Started
Everything you need to start integrating the MexicoP2P Partner API — API keys, authentication, rate limits, and error handling.
What is the MexicoP2P Partner API?
MexicoP2P provides crypto-to-peso infrastructure for your platform. You make a few REST API calls to create USDC/USDT sell orders, and the MexicoP2P marketplace handles escrow on Starknet, buyer matching, SPEI payment verification, and crypto release — all automatically.
Base URL:
https://mexicop2p.org/api/v1Get your API key
- Sign up for a partner account at mexicop2p.org/partners
- Open the Partner Dashboard and navigate to API Keys
- Click Generate API Key — copy it immediately (we hash it with bcrypt and can't show it again)
- Copy your Webhook Secret from the same page (used to verify webhook signatures)
Key format
| Part | Value | Length |
|---|---|---|
| Prefix | mp2p_ | 5 chars |
| Secret | Random hex | 64 chars |
| Total | 69 chars |
Example: mp2p_a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2
Key management
- Each partner gets one active key at a time
- Rotate keys by generating a new one and updating your integration
- Keys cannot be recovered — generate a new one if lost
Authentication
All requests require your API key in the X-API-Key header:
curl -H "X-API-Key: mp2p_your_api_key_here" \
https://mexicop2p.org/api/v1/healthAuthentication errors
| Error Code | HTTP | Meaning |
|---|---|---|
MISSING_API_KEY | 401 | No X-API-Key header in the request |
INVALID_API_KEY | 401 | Key doesn't match any active partner |
PARTNER_INACTIVE | 403 | Partner account is not active |
PARTNER_SUSPENDED | 403 | Partner KYB status is suspended |
IP whitelisting
You can restrict API access to specific IP addresses from the Partner Dashboard. When enabled, requests from non-whitelisted IPs receive a 403 with error code IP_NOT_ALLOWED.
Leave the whitelist empty to allow all IPs.
Webhook signatures
Webhook deliveries include HMAC-SHA256 signatures so you can verify they came from MexicoP2P. See Signature Verification for implementation details.
| Header | Description |
|---|---|
X-Webhook-Id | Unique delivery ID |
X-Webhook-Signature | HMAC-SHA256 hex signature |
X-Webhook-Timestamp | Unix timestamp (seconds) |
Signature is computed over {timestamp}.{JSON payload} using your webhook secret.
Rate limits and tiers
| Tier | Requests/min | Monthly users | Monthly volume | Revenue share | Price |
|---|---|---|---|---|---|
| Free | 50 | 10 | 50,000 MXN | 30% of your fees | $0 |
| Growth | 200 | 500 | 1,000,000 MXN | 20% of your fees | $199/mo |
| Enterprise | 1,000 | Unlimited | Custom | Custom | Custom |
MexicoP2P does not charge fees to end users. You optionally set a feePercent on quotes — that's your revenue. MexicoP2P takes a share of it based on your tier. See Pricing.
Rate limit headers
Every response includes these headers:
| Header | Description |
|---|---|
X-RateLimit-Limit | Max requests per minute for your tier |
X-RateLimit-Remaining | Requests remaining in the current window |
X-RateLimit-Reset | Unix timestamp when the window resets |
Retry-After | Seconds to wait (only on 429 responses) |
When you exceed the limit, you'll receive a 429 response with error code RATE_LIMITED. Use the Retry-After header value before retrying.
Volume and user limits
- Volume limits are checked on each
POST /ordersrequest (daily and monthly). ReturnsVOLUME_LIMIT_EXCEEDEDwhen exceeded. - User limits are checked on
POST /users. ReturnsUSER_LIMIT_REACHEDwhen exceeded.
Best practices
- Cache exchange rates (valid for 5 minutes) instead of fetching per request
- Use webhooks instead of polling order status
- Implement exponential backoff when receiving
429responses
Error codes
All errors follow a consistent format:
{
"error": "ERROR_CODE",
"message": "Human-readable error description"
}Full error code table
| Code | HTTP | Description |
|---|---|---|
MISSING_API_KEY | 401 | No X-API-Key header in request |
INVALID_API_KEY | 401 | API key doesn't match any active partner |
PARTNER_INACTIVE | 403 | Partner account is not active |
PARTNER_SUSPENDED | 403 | Partner KYB status is suspended |
IP_NOT_ALLOWED | 403 | Client IP not in partner's whitelist |
RATE_LIMITED | 429 | Request rate limit exceeded for tier |
VALIDATION_ERROR | 400 | Missing or invalid request fields |
INVALID_CLABE | 400 | CLABE failed 18-digit validation with check digit |
INVALID_QUOTE | 404 | Quote not found or doesn't belong to partner |
QUOTE_EXPIRED | 410 | Quote TTL (5 minutes) has elapsed |
QUOTE_USED | 409 | Quote already consumed by an order |
QUOTE_USER_MISMATCH | 400 | Quote's partnerUserRef doesn't match request |
NOT_FOUND | 404 | Resource doesn't exist |
DUPLICATE_USER | 409 | User with this partnerUserRef already exists |
USER_LIMIT_REACHED | 403 | Partner hit tier's maximum user count |
VOLUME_LIMIT_EXCEEDED | 403 | Partner exceeded daily or monthly volume limit |
KYC_NOT_AVAILABLE | 400 | Partner uses PARTNER_MANAGED KYC model |
KYC_LIMIT_REACHED | 403 | Monthly KYC verification limit exceeded |
KYC_SESSION_FAILED | 502 | Upstream KYC provider returned an error |
HTTP status code summary
| Status | Meaning |
|---|---|
| 200 | Success |
| 201 | Created (new resource) |
| 400 | Validation error |
| 401 | Authentication failed |
| 403 | Forbidden (inactive, suspended, limit reached, IP blocked) |
| 404 | Not found |
| 409 | Conflict (duplicate, already used) |
| 410 | Gone (expired) |
| 429 | Rate limited |
| 500 | Internal server error |
| 502 | Bad gateway (external service error) |
Quick links
- How It Works — Architecture, trade flow, glossary, and KYC models
- Quickstart — Create your first order in 5 steps
- API Reference — All endpoints with examples
- Webhooks — Event delivery and signature verification
LLM context
AI coding assistants can use machine-readable API context files to help you integrate:
| File | URL | Description |
|---|---|---|
llms.txt | /llms.txt | Concise API overview for AI context windows |
llms-full.txt | /llms-full.txt | Full documentation as plain text |
Add to your project's AI config (e.g., .cursor/rules or CLAUDE.md):
@https://docs.mexicop2p.org/llms.txt