Welcome

The Mintarex API provides programmatic access to OTC crypto trading, wallet management, and real-time market data for institutional clients.

Mintarex is an OTC (over-the-counter) trading platform — not an exchange. We use a Request-for-Quote (RFQ) model: you request a price, we lock it, you execute with zero slippage. This is what treasury desks, payment processors, and remittance companies need.

What you can do with the API

• Trade — Request RFQ quotes and execute trades across 200+ crypto pairs and 6 fiat currencies (USD, EUR, GBP, CAD, AED, INR)
• Wallets — Check balances, get deposit addresses, submit withdrawals across 63 blockchain networks
• Market Data — Real-time price feeds via Server-Sent Events (SSE)
• Webhooks — Receive push notifications for trade fills, deposits, and withdrawals
• Account — View balances, fee rates, and transaction limits

Supported currencies

Common coin & network identifiers

Use GET /v1/networks?coin={SYMBOL} for the complete list. Here are the most common ones:

For the full list of 200+ coins and 63 networks, call GET /v1/networks (no authentication required).

Base URL

All API requests are made to:

https://institutional.mintarex.com/v1

All requests must use HTTPS. HTTP requests are automatically redirected.

Health check

GET https://institutional.mintarex.com/health

Response:
{
  "ok": true,
  "service": "mintarex-otc-gateway",
  "version": "0.0.1",
  "timestamp": "2026-04-09T09:33:04.593Z",
  "uptime_seconds": 3600
}

Authentication

Every API request must include four authentication headers:

Optional headers

Generating the API Key

1. Log in to the Mintarex Dashboard with a corporate account
2. Complete corporate KYC verification (must be approved)
3. Navigate to Settings → API Keys
4. Click Create API Key
5. Select your desired permissions (scopes)
6. Add at least one IP address to the whitelist (required for production keys)
7. Your API key and secret will be displayed once — save the secret immediately

Key format

API Key:    mxn_live_a8f3b2c1d4e5f6a7b8c9d0e1   (33 characters, public)
API Secret: YWJjZGVmZ2hpamtsbW5vcH...          (64 characters, secret — save immediately)

Permission scopes

IP whitelisting

Production keys require at least one IP address. Requests from non-whitelisted IPs are rejected with 403 IP_NOT_WHITELISTED. Supports IPv4, IPv6, and CIDR notation (e.g. 203.0.113.0/24).

Signing Requests

Every authenticated request must be signed with HMAC-SHA256 using your API secret.

Step 1: Build the canonical string

Concatenate with newline (\n) separator:

canonical = METHOD + "\n" + PATH + "\n" + TIMESTAMP + "\n" + NONCE + "\n" + BODY_HASH

Step 2: Compute the HMAC

signature = HMAC-SHA256(api_secret, canonical_string).hex()   // 64 hex characters

Step 3: Send the headers

MX-API-KEY: mxn_live_a8f3b2c1d4e5f6a7b8c9d0e1
MX-TIMESTAMP: 1712582345
MX-NONCE: 550e8400-e29b-41d4-a716-446655440000
MX-SIGNATURE: 7d9b2c5f8a1e4b6d9c2e5f8a1b4c7d0e3f6a9b2c5f8a1e4b6d9c2e5f8a1b4c7

Code Samples

Complete signing and request examples in 5 languages.

Node.js

const crypto = require('node:crypto');
const https = require('node:https');

const API_KEY    = 'mxn_live_your_key_here';
const API_SECRET = 'your_secret_here';
const BASE       = 'https://institutional.mintarex.com';

function signedRequest(method, path, body = '') {
  const timestamp = Math.floor(Date.now() / 1000).toString();
  const nonce     = crypto.randomUUID();
  const bodyStr   = (body !== null && typeof body === 'object') ? JSON.stringify(body) : (body || '');
  const bodyHash  = crypto.createHash('sha256').update(bodyStr).digest('hex');
  const canonical = [method, path, timestamp, nonce, bodyHash].join('\n');
  const signature = crypto.createHmac('sha256', API_SECRET).update(canonical).digest('hex');

  return {
    headers: {
      'MX-API-KEY': API_KEY, 'MX-TIMESTAMP': timestamp,
      'MX-NONCE': nonce, 'MX-SIGNATURE': signature,
      'Content-Type': 'application/json',
    },
    body: bodyStr,
  };
}

// GET example
const { headers } = signedRequest('GET', '/v1/account/balances');
https.get(new URL('/v1/account/balances', BASE), { headers }, (res) => {
  let d = ''; res.on('data', c => d += c);
  res.on('end', () => console.log(JSON.parse(d)));
});

// POST example (request a quote)
const quoteBody = { base: 'BTC', quote: 'USD', side: 'buy', amount: '1000', amount_type: 'quote' };
const req = signedRequest('POST', '/v1/rfq', quoteBody);
const r = https.request(new URL('/v1/rfq', BASE), {
  method: 'POST', headers: req.headers,
}, (res) => {
  let d = ''; res.on('data', c => d += c);
  res.on('end', () => console.log(JSON.parse(d)));
});
r.write(req.body); r.end();

Python

import hashlib, hmac, json, time, uuid, requests

API_KEY    = 'mxn_live_your_key_here'
API_SECRET = 'your_secret_here'
BASE       = 'https://institutional.mintarex.com'

def signed_request(method, path, body=None):
    timestamp = str(int(time.time()))
    nonce     = str(uuid.uuid4())
    body_str  = json.dumps(body) if body else ''
    body_hash = hashlib.sha256(body_str.encode()).hexdigest()
    canonical = f"{method}\n{path}\n{timestamp}\n{nonce}\n{body_hash}"
    signature = hmac.new(API_SECRET.encode(), canonical.encode(), hashlib.sha256).hexdigest()

    headers = {
        'MX-API-KEY': API_KEY, 'MX-TIMESTAMP': timestamp,
        'MX-NONCE': nonce, 'MX-SIGNATURE': signature,
        'Content-Type': 'application/json',
    }
    return headers, body_str

# GET example
headers, _ = signed_request('GET', '/v1/account/balances')
resp = requests.get(f'{BASE}/v1/account/balances', headers=headers)
print(resp.json())

# POST example (request a quote)
body = {'base': 'BTC', 'quote': 'USD', 'side': 'buy', 'amount': '1000', 'amount_type': 'quote'}
headers, data = signed_request('POST', '/v1/rfq', body)
resp = requests.post(f'{BASE}/v1/rfq', headers=headers, data=data)
print(resp.json())

Go

package main

import (
    "crypto/hmac"
    "crypto/sha256"
    "encoding/hex"
    "fmt"
    "io"
    "net/http"
    "strings"
    "time"

    "github.com/google/uuid"
)

const (
    apiKey    = "mxn_live_your_key_here"
    apiSecret = "your_secret_here"
    baseURL   = "https://institutional.mintarex.com"
)

func signRequest(method, path, body string) http.Header {
    timestamp := fmt.Sprintf("%d", time.Now().Unix())
    nonce := uuid.New().String()

    h := sha256.Sum256([]byte(body))
    bodyHash := hex.EncodeToString(h[:])

    canonical := strings.Join([]string{method, path, timestamp, nonce, bodyHash}, "\n")
    mac := hmac.New(sha256.New, []byte(apiSecret))
    mac.Write([]byte(canonical))
    signature := hex.EncodeToString(mac.Sum(nil))

    headers := http.Header{}
    headers.Set("MX-API-KEY", apiKey)
    headers.Set("MX-TIMESTAMP", timestamp)
    headers.Set("MX-NONCE", nonce)
    headers.Set("MX-SIGNATURE", signature)
    headers.Set("Content-Type", "application/json")
    return headers
}

func main() {
    path := "/v1/account/balances"
    req, _ := http.NewRequest("GET", baseURL+path, nil)
    req.Header = signRequest("GET", path, "")

    resp, err := http.DefaultClient.Do(req)
    if err != nil { panic(err) }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}

Java

import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URI;
import java.net.http.*;
import java.security.MessageDigest;
import java.time.Instant;
import java.util.UUID;

public class MintarexApi {
    static final String API_KEY    = "mxn_live_your_key_here";
    static final String API_SECRET = "your_secret_here";
    static final String BASE_URL   = "https://institutional.mintarex.com";

    static String sha256(String data) throws Exception {
        MessageDigest md = MessageDigest.getInstance("SHA-256");
        byte[] hash = md.digest(data.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte b : hash) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    static String hmacSha256(String key, String data) throws Exception {
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(new SecretKeySpec(key.getBytes("UTF-8"), "HmacSHA256"));
        byte[] hash = mac.doFinal(data.getBytes("UTF-8"));
        StringBuilder sb = new StringBuilder();
        for (byte b : hash) sb.append(String.format("%02x", b));
        return sb.toString();
    }

    public static void main(String[] args) throws Exception {
        String method    = "GET";
        String path      = "/v1/account/balances";
        String timestamp = String.valueOf(Instant.now().getEpochSecond());
        String nonce     = UUID.randomUUID().toString();
        String bodyHash  = sha256("");
        String canonical = method + "\n" + path + "\n" + timestamp + "\n" + nonce + "\n" + bodyHash;
        String signature = hmacSha256(API_SECRET, canonical);

        HttpRequest request = HttpRequest.newBuilder()
            .uri(URI.create(BASE_URL + path))
            .header("MX-API-KEY", API_KEY)
            .header("MX-TIMESTAMP", timestamp)
            .header("MX-NONCE", nonce)
            .header("MX-SIGNATURE", signature)
            .GET().build();

        HttpResponse<String> response = HttpClient.newHttpClient()
            .send(request, HttpResponse.BodyHandlers.ofString());
        System.out.println(response.body());
    }
}

C#

using System.Security.Cryptography;
using System.Text;

var apiKey    = "mxn_live_your_key_here";
var apiSecret = "your_secret_here";
var baseUrl   = "https://institutional.mintarex.com";

string Sha256(string data) {
    var bytes = SHA256.HashData(Encoding.UTF8.GetBytes(data));
    return Convert.ToHexString(bytes).ToLower();
}

string HmacSha256(string key, string data) {
    using var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key));
    var hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
    return Convert.ToHexString(hash).ToLower();
}

var method    = "GET";
var path      = "/v1/account/balances";
var timestamp = DateTimeOffset.UtcNow.ToUnixTimeSeconds().ToString();
var nonce     = Guid.NewGuid().ToString();
var bodyHash  = Sha256("");
var canonical = $"{method}\n{path}\n{timestamp}\n{nonce}\n{bodyHash}";
var signature = HmacSha256(apiSecret, canonical);

using var client = new HttpClient();
var request = new HttpRequestMessage(HttpMethod.Get, baseUrl + path);
request.Headers.Add("MX-API-KEY", apiKey);
request.Headers.Add("MX-TIMESTAMP", timestamp);
request.Headers.Add("MX-NONCE", nonce);
request.Headers.Add("MX-SIGNATURE", signature);

var response = await client.SendAsync(request);
Console.WriteLine(await response.Content.ReadAsStringAsync());

PHP

<?php
$apiKey    = 'mxn_live_your_key_here';
$apiSecret = 'your_secret_here';
$baseUrl   = 'https://institutional.mintarex.com';

function signedRequest($method, $path, $body = '') {
    global $apiKey, $apiSecret;
    $timestamp = (string)time();
    $nonce     = sprintf('%s-%s-%s-%s-%s',
        bin2hex(random_bytes(4)), bin2hex(random_bytes(2)),
        bin2hex(random_bytes(2)), bin2hex(random_bytes(2)),
        bin2hex(random_bytes(6)));
    $bodyHash  = hash('sha256', $body);
    $canonical = implode("\n", [$method, $path, $timestamp, $nonce, $bodyHash]);
    $signature = hash_hmac('sha256', $canonical, $apiSecret);

    return [
        'MX-API-KEY: '    . $apiKey,
        'MX-TIMESTAMP: '  . $timestamp,
        'MX-NONCE: '      . $nonce,
        'MX-SIGNATURE: '  . $signature,
        'Content-Type: application/json',
    ];
}

// GET example
$path = '/v1/account/balances';
$headers = signedRequest('GET', $path);
$ch = curl_init($baseUrl . $path);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

// POST example
$path = '/v1/rfq';
$body = json_encode(['base'=>'BTC','quote'=>'USD','side'=>'buy','amount'=>'1000','amount_type'=>'quote']);
$headers = signedRequest('POST', $path, $body);
$ch = curl_init($baseUrl . $path);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;
?>

cURL

# Set credentials
API_KEY="mxn_live_your_key_here"
API_SECRET="your_secret_here"

# Build signature components
METHOD="GET"
PATH="/v1/account/balances"
TIMESTAMP=$(date +%s)
NONCE=$(python3 -c "import uuid; print(uuid.uuid4())")
BODY_HASH=$(echo -n "" | sha256sum | cut -d' ' -f1)

# Sign
CANONICAL=$(printf "%s\n%s\n%s\n%s\n%s" "$METHOD" "$PATH" "$TIMESTAMP" "$NONCE" "$BODY_HASH")
SIGNATURE=$(echo -ne "$CANONICAL" | openssl dgst -sha256 -hmac "$API_SECRET" | cut -d' ' -f2)

# Request
curl -s "https://institutional.mintarex.com${PATH}" \
  -H "MX-API-KEY: ${API_KEY}" \
  -H "MX-TIMESTAMP: ${TIMESTAMP}" \
  -H "MX-NONCE: ${NONCE}" \
  -H "MX-SIGNATURE: ${SIGNATURE}" | python3 -m json.tool

Rate Limits

Rate limits are enforced per API key using a sliding window. Limits vary by endpoint type and your account tier.

Endpoint classification

Rate limit headers

Every response includes IETF-standard rate limit headers:

Error Codes

All errors return JSON with flat error and message fields:

{ "error": "invalid_signature", "message": "Request signature verification failed" }

HTTP status codes

Authentication error codes

Trading error codes

Idempotency

For safe retries on POST requests (orders, withdrawals), include the MX-IDEMPOTENCY-KEY header with a UUID v4.

MX-IDEMPOTENCY-KEY: 550e8400-e29b-41d4-a716-446655440001

• Same key + same body within 24h: returns the cached response from the first request
• Same key + different body: returns 422 Unprocessable Entity
• Keys expire after 24 hours

Pagination

List endpoints (trades, deposits, withdrawals) support cursor-based pagination.

Query parameters

Example

GET /v1/trades?limit=20&offset=0&from=2026-04-01T00:00:00Z&sort=desc

Response envelope

{
  "data": [ ... ],
  "pagination": {
    "total": 145,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Get Balances

GET /v1/account/balances

Returns all wallet balances. Requires read:wallet scope.

Query parameters

Response

{
  "balances": [
    {
      "currency": "BTC",
      "currency_type": "crypto",
      "available": "1.25000000",
      "locked": "0.10000000",
      "pending_in": "0.05000000",
      "pending_out": "0.00000000",
      "total": "1.35000000",
      "usd_value": "88290.15",
      "usd_price": "65400.11"
    },
    {
      "currency": "USD",
      "currency_type": "fiat",
      "available": "50000.00",
      "locked": "0.00",
      "pending_in": "0.00",
      "pending_out": "0.00",
      "total": "50000.00"
    }
  ],
  "timestamp": "2026-04-09T10:30:00.000Z"
}

Get Single Balance

GET /v1/account/balance/{currency}

Returns balance for a specific currency across all wallet types. Requires read:wallet scope.

Response

{
  "currency": "USDT",
  "currency_type": "crypto",
  "total_available": "125000.00000000",
  "total_locked": "5000.00000000",
  "total": "130000.00000000",
  "by_wallet_type": [
    { "wallet_type": "funding", "available": "125000.00000000", "locked": "5000.00000000" }
  ],
  "timestamp": "2026-04-09T10:30:00.000Z"
}

Get Fee Rates

GET /v1/account/fees

Returns your account's fee rates (may differ from defaults for VIP/institutional accounts). Requires read:account scope.

{
  "trading_fee_rate": "0.005",
  "fiat_withdrawal_fee_rate": "0.001",
  "note": "Fee rates expressed as decimals (0.005 = 0.5%)",
  "timestamp": "2026-04-09T10:30:00.000Z"
}

Get Transaction Limits

GET /v1/account/limits

Returns daily and monthly transaction limits by type. Requires read:account scope.

{
  "limits": {
    "bank_deposit": { "min_amount": "100.00", "max_amount": "1000000.00", "daily_limit": "1000000.00", "monthly_limit": "5000000.00" },
    "crypto_withdrawal": { "min_amount": "10.00", "max_amount": "500000.00", "daily_limit": "500000.00", "monthly_limit": "2000000.00" },
    "fiat_withdrawal": { "min_amount": "100.00", "max_amount": "500000.00", "daily_limit": "500000.00", "monthly_limit": "2000000.00" }
  },
  "account_type": "corporate",
  "timestamp": "2026-04-09T10:30:00.000Z"
}

Request Quote (RFQ)

POST /v1/rfq

Request a locked-price quote. Valid for 30 seconds. Requires trade:quote scope.

Request

// Crypto/fiat trade
{ "base": "BTC", "quote": "USD", "side": "buy", "amount": "1000.00", "amount_type": "quote" }

// Crypto-to-crypto swap
{ "base": "ETH", "quote": "BTC", "side": "buy", "amount": "1.0", "amount_type": "base", "from_network": "eth", "to_network": "btc" }

Response

{
  "quote_id": "550e8400-e29b-41d4-a716-446655440000",
  "base": "BTC",
  "quote": "USD",
  "side": "buy",
  "network": "btc",
  "price": "72014.25000000",
  "base_amount": "0.01388614",
  "quote_amount": "1000.00",
  "expires_at": "2026-04-09T14:32:18Z",
  "expires_in_ms": 30000
}

For crypto-to-crypto swaps, additional fields are included:

{
  "is_swap": true,
  "from_network": "eth",
  "to_network": "btc",
  ...
}

Response fields

Accept Quote

POST /v1/rfq/{quote_id}/accept

Execute a previously received quote before it expires. Requires trade:execute scope.

Request

The quote_id is in the URL path. The only body field is the idempotency key — all trade parameters are stored server-side in the quote.

{ "idempotency_key": "550e8400-e29b-41d4-a716-446655440000" }

Response (200 — filled)

{
  "trade_id": "550e8400-e29b-41d4-a716-446655440001",
  "status": "filled",
  "base": "BTC",
  "quote": "USD",
  "side": "buy",
  "network": "btc",
  "price": "72014.25000000",
  "base_amount": "0.01388614",
  "quote_amount": "1000.00",
  "filled_at": "2026-04-09T14:32:01Z"
}

For crypto-to-crypto swaps, additional fields: is_swap, from_network, to_network.

Get Trade History

GET /v1/trades

Paginated list of executed trades. Requires read:trade scope.

Query parameters

Response

{
  "data": [
    {
      "trade_id": "tr_550e8400...",
      "base": "BTC", "quote": "USD", "side": "buy",
      "price": "72014.25", "base_amount": "0.01388614",
      "quote_amount": "1000.00",
      "status": "filled", "created_at": "2026-04-09T14:32:01Z"
    }
  ],
  "pagination": { "total": 23, "limit": 50, "offset": 0, "has_more": false }
}

Get Trade Detail

GET /v1/trade/{trade_id}

Returns details of a single trade. Requires read:trade scope.

Get Deposit Address

GET /v1/crypto/deposit-address?coin={symbol}&network={network}

Returns (or creates) a deposit address for the specified coin and network. If no network is specified, the default deposit-enabled network is used. Requires read:wallet scope.

Query parameters

Response

{
  "address": "bc1q59c6n76ta7rgh093mlxr86kvhled77yux6km8r",
  "coin": "BTC",
  "network": "btc",
  "memo_required": false,
  "min_deposit": "0.00010000",
  "required_confirmations": 3,
  "timestamp": "2026-04-12T12:35:46.123Z"
}

Get Crypto Deposits

GET /v1/crypto/deposits

Paginated list of crypto deposits. Requires read:wallet scope. Supports pagination and filters.

Query parameters

Response

{
  "data": [
    {
      "deposit_id": "550e8400-e29b-41d4-a716-446655440000",
      "coin": "BTC",
      "network": "btc",
      "amount": "0.50000000",
      "tx_hash": "abc123def456...",
      "from_address": "1A1zP1eP5QGefi2...",
      "confirmations": 6,
      "required_confirmations": 3,
      "status": "completed",
      "detected_at": "2026-04-09T10:00:00.000Z",
      "updated_at": "2026-04-09T10:45:00.000Z"
    }
  ],
  "pagination": { "total": 5, "limit": 50, "offset": 0, "has_more": false }
}

Submit Crypto Withdrawal

POST /v1/crypto/withdraw

Submit a crypto withdrawal request. The withdrawal enters pending_review status and requires admin approval before on-chain execution. The destination address must be pre-whitelisted and past its 24-hour cooling period. Requires withdraw:crypto scope + allow_withdrawals enabled.

Request

{
  "coin": "BTC",
  "network": "btc",
  "amount": "0.1",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "address_tag": "",
  "idempotency_key": "my-withdrawal-20260412-001"
}

Fields

Response

{
  "withdrawal_id": "550e8400-e29b-41d4-a716-446655440000",
  "reference": "MNX-CW26041200001",
  "status": "pending_review",
  "coin": "BTC",
  "network": "btc",
  "amount": "0.10000000",
  "fee": "0.00050000",
  "total_deducted": "0.10050000",
  "amount_usd": "4215.05",
  "to_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "message": "Withdrawal request submitted for admin review."
}

Get Crypto Withdrawals

GET /v1/crypto/withdrawals

Paginated list of crypto withdrawals. Requires read:wallet scope. Same filter parameters as Get Deposits.

Response

{
  "data": [
    {
      "withdrawal_id": "550e8400-e29b-41d4-a716-446655440000",
      "reference": "MNX-CW26041200001",
      "coin": "BTC",
      "network": "btc",
      "amount": "0.10000000",
      "fee": "0.00050000",
      "amount_usd": "4215.05",
      "to_address": "bc1qxy2kgdygjrsqtzq2n0yrf...",
      "tx_hash": null,
      "status": "pending_review",
      "reject_reason": null,
      "created_at": "2026-04-12T11:00:00.000Z",
      "completed_at": null
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false }
}

Get Withdrawal Detail

GET /v1/crypto/withdrawals/{uuid}

Returns a single withdrawal with full detail including tx_hash and explorer_url when available. Requires read:wallet scope.

Add Allowlist Address

POST /v1/crypto/withdrawal-addresses

Add a crypto address to the withdrawal allowlist. Triggers an email confirmation. After confirmation, a 24-hour cooling period begins before the address can be used for withdrawals. Requires withdraw:crypto scope.

Request

{
  "currency": "BTC",
  "network": "btc",
  "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "address_tag": "",
  "label": "Cold Storage Vault"
}

Response (201)

{
  "success": true,
  "address_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "pending",
  "message": "Confirmation email sent. Click the link to confirm, then wait 24-hour cooling period."
}

List Allowlisted Addresses

GET /v1/crypto/withdrawal-addresses

Returns all addresses in your withdrawal allowlist with status and usage stats. Requires read:wallet scope. Filter by currency, network, or status.

Response

{
  "data": [
    {
      "address_uuid": "550e8400-e29b-41d4-a716-446655440000",
      "currency": "BTC",
      "network": "btc",
      "address": "bc1qxy2kgdygjrsqtzq2n0yrf...",
      "address_tag": null,
      "label": "Cold Storage Vault",
      "status": "active",
      "cooling_until": null,
      "is_usable": true,
      "withdrawal_count": 5,
      "total_withdrawn_amount": "1.50000000",
      "last_withdrawal_at": "2026-04-10T14:30:00.000Z",
      "created_at": "2026-04-01T09:00:00.000Z"
    }
  ],
  "pagination": { "total": 1, "limit": 50, "offset": 0, "has_more": false }
}

Revoke Address

DELETE /v1/crypto/withdrawal-addresses/{uuid}

Permanently revokes an address from the withdrawal allowlist. The address can no longer be used for withdrawals. Requires withdraw:crypto scope.

Response

{
  "success": true,
  "address_uuid": "550e8400-e29b-41d4-a716-446655440000",
  "status": "revoked"
}

Webhooks

Register HTTPS endpoints to receive push notifications for trades, deposits, withdrawals, and account events.

How it works

1. Register a webhook URL via POST /v1/webhooks
2. Subscribe to specific event types
3. Mintarex signs each delivery with HMAC-SHA256 using your webhook secret
4. Your server verifies the signature and responds with 200 OK within 10 seconds
5. Failed deliveries retry with exponential backoff (30s, 1m, 2m, 4m, 8m, 16m, 32m, 64m — max 8 attempts)

Webhook delivery headers

Delivery payload

{
  "id": "evt_550e8400...",
  "type": "trade.executed",
  "created_at": "2026-04-09T14:32:01Z",
  "data": {
    "trade_id": "tr_550e8400...",
    "base": "BTC", "quote": "USD",
    "price": "65432.10", "base_amount": "0.01521"
  }
}

Webhook Event Types

Verifying Webhook Signatures

Always verify the X-Mintarex-Signature header before processing.

Node.js

const crypto = require('node:crypto');

function verifyWebhook(rawBody, signature, secret) {
  const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature, 'hex'), Buffer.from(expected, 'hex'));
}

app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  if (!verifyWebhook(req.body, req.headers['x-mintarex-signature'], WEBHOOK_SECRET)) {
    return res.status(401).send('Invalid signature');
  }
  const event = JSON.parse(req.body);
  console.log(event.type, event.data);
  res.status(200).send('OK');
});

Python

import hmac, hashlib

def verify_webhook(body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature, expected)

# In Flask:
@app.route('/webhook', methods=['POST'])
def webhook():
    if not verify_webhook(request.data, request.headers['X-Mintarex-Signature'], WEBHOOK_SECRET):
        return 'Invalid signature', 401
    event = request.json
    print(event['type'], event['data'])
    return 'OK', 200

Real-time Streaming (SSE)

Mintarex provides Server-Sent Events (SSE) streams for real-time price updates and account events. SSE uses a two-step authentication flow:

1. Get a stream token — POST /v1/stream/token (authenticated via HMAC like any other endpoint)
2. Connect to SSE — Pass the token as a query parameter. The SSE endpoints are on the main API, not the gateway.

Step 1: Get Stream Token

POST /v1/stream/token

Returns a single-use, 60-second token. Requires stream:market or stream:account scope.

// Response
{ "token": "a1b2c3d4e5f6...64 hex chars...", "expires_in": 60 }

Step 2: Connect to Price Stream

GET https://api.mintarex.com/api/v1/corporate-stream/prices?token={token}&instruments=BTC_USD,ETH_USD

Real-time price updates. Requires stream:market scope.

Step 2 (alt): Connect to Account Stream

GET https://api.mintarex.com/api/v1/corporate-stream/account?token={token}

Real-time account events (trade fills, deposits, withdrawals). Requires stream:account scope.

Account stream event types

• trade.executed — trade filled
• deposit.detected — deposit seen on-chain
• deposit.confirmed — deposit credited to balance
• withdrawal.requested — withdrawal submitted
• withdrawal.approved — withdrawal approved by admin
• withdrawal.completed — withdrawal confirmed on-chain
• withdrawal.cancelled — withdrawal cancelled or rejected

Node.js example

const EventSource = require('eventsource');

// Step 1: Get token (using your signedRequest helper)
const tokenReq = signedRequest('POST', '/v1/stream/token', '');
const tokenRes = await fetch(BASE + '/v1/stream/token', {
  method: 'POST', headers: tokenReq.headers,
});
const { token } = await tokenRes.json();

// Step 2: Connect to SSE (note: different host — api.mintarex.com, not institutional)
const url = `https://api.mintarex.com/api/v1/corporate-stream/prices?token=${token}&instruments=BTC_USD,ETH_USD`;
const es = new EventSource(url);

es.onmessage = (event) => {
  const data = JSON.parse(event.data);
  console.log(data.instrument, data.price, data.change_24h);
};

Stream limits

• Max 3 concurrent SSE connections per API key
• Connections auto-close after 1 hour (reconnect with a new token)
• Heartbeat sent every 15 seconds (detect stale connections)
• Stream token is single-use and expires in 60 seconds

Changelog

2026-04-13 — v1.1.0

• Crypto-to-crypto swaps: RFQ now supports crypto/crypto pairs (e.g. ETH/BTC) with from_network and to_network parameters
• Transaction limits enforced on API trades (same daily/monthly limits as dashboard)
• API key prefix changed from mx_live_ to mxn_live_ (33 characters total)
• Simplified accept flow: only idempotency_key required in request body (no echo-back fields)
• Dashboard Developer page for self-service key management with MFA protection
• Webhook management via dashboard UI
• Fixed error response format documentation (flat error + message, not nested)
• Fixed webhook event types to match actual implementation
• Added comprehensive trading error codes to documentation

2026-04-09 — v1.0.0 (Initial Release)

• Account endpoints: balances, single balance, fees, limits
• RFQ trading: quote with all-in spread pricing + accept flow
• Trade history: paginated list + single trade detail
• Public reference data: instruments (4,066 pairs), networks, fee schedule
• Crypto wallet: deposit addresses, deposits, withdrawals with address whitelisting
• HMAC-SHA256 authentication with nonce + timestamp replay protection
• AES-256-GCM encrypted API key storage with HKDF key derivation
• All-in pricing model: OTC spread baked into quoted price, no separate fees
• Price feed via Varnish cache (same source as dashboard Markets page)
• Webhook delivery with HMAC signature verification
• SSE streaming for prices and account events
• IETF-standard rate limit headers (RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset)
• Full request audit logging to api_request_log table
• Code samples in 7 languages: Node.js, Python, Go, Java, C#, PHP, cURL

Support

Need help integrating? We're here to help.

• Email: business@mintarex.com
• API Status: institutional.mintarex.com/health
• Website: mintarex.com