Authentication

The MP Merchant API uses HMAC-SHA256 signed requests for API key authentication. Your secret is never transmitted — only a time-limited signature derived from it.

API keys

Each API key has two parts:

key_id — Public identifier, included in every request. Prefixed mk_live_ or mk_test_.
secret — Private 64-character hex string. Never transmitted, only used to sign requests.

🚨 Keep your secret safe

Store the secret in an environment variable or secrets manager. Never commit it to source code or log it. If compromised, revoke the key immediately from your dashboard.

Signing requests

Every authenticated request must include an Authorization header with a signed Bearer token:

Authorization header format

Authorization: Bearer {key_id}:{unix_timestamp}:{hmac_signature}

The HMAC-SHA256 signature is computed over the string "{key_id}.{unix_timestamp}" using your secret as the key.

Step-by-step

Get the current Unix timestamp (seconds since epoch)
Compute HMAC-SHA256(key=secret, message="{key_id}.{timestamp}")
Hex-encode the result
Set header: Authorization: Bearer {key_id}:{timestamp}:{hex_signature}

⚠️ Timestamp tolerance

Requests with a timestamp more than 5 minutes in the past or future are rejected. Ensure your server clock is synchronized (NTP).

Code examples

JavaScript

const crypto = require('crypto');

function buildAuthHeader(keyId, secret) {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const message = `${keyId}.${timestamp}`;
  const signature = crypto
    .createHmac('sha256', secret)
    .update(message)
    .digest('hex');
  return `Bearer ${keyId}:${timestamp}:${signature}`;
}

// Usage
const headers = {
  'Authorization': buildAuthHeader(process.env.MP_KEY_ID, process.env.MP_SECRET),
  'Content-Type': 'application/json',
};

Test vs live keys

Prefix	Environment	Behavior
`mk_test_`	Sandbox	No real blockchain transactions. Use for development and testing.
`mk_live_`	Production	Real USDT transactions. Requires active merchant account.

Managing keys

POST

/v1/merchants/api-keys

Create a new API key

🚨 Secret shown once

The secret is returned only on creation and cannot be retrieved again.

Body parameters

namestringoptional

Human-readable label for this key, e.g. "Production".

environmentstringrequired

Environment the key is valid for.One of: live, test

Returns Returns the key_id and secret. The secret is shown only once — store it immediately.

Request

bash

curl -X POST https://api.mpchat.com/v1/merchants/api-keys \
  -H "Authorization: Bearer mk_live_...:{ts}:{sig}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production",
    "environment": "live"
  }'

Response 201

JSON

{
  "key_id": "mk_live_01HQ8ZTXV...",
  "secret": "4f3c2e1d0a9b8c7d6e5f4c3b2a1098...",
  "name": "Production",
  "environment": "live",
  "created_at": "2024-01-15T10:01:00Z"
}

DELETE

/v1/merchants/api-keys/{key_id}

Revoke an API key

Path parameters

key_idstringrequired

The key_id to revoke, e.g. mk_live_01HQ...

Returns Returns a confirmation message. The key is immediately invalidated.

Request

bash

curl -X DELETE \
  https://api.mpchat.com/v1/merchants/api-keys/mk_live_01HQ... \
  -H "Authorization: Bearer mk_live_...:{ts}:{sig}"

Response 200

JSON

{"message": "API key deleted"}

Next: Orders API