Authentication

The Merx API supports two authentication methods: API keys for programmatic access and JWT tokens for web sessions.

API Key Authentication

Pass your API key via the X-API-Key header. Keys are prefixed with sk_live_ and can be scoped with specific permissions.

Using an API key

curl https://merx.exchange/api/v1/balance \
  -H "X-API-Key: sk_live_your_key_here"

JWT Authentication

Web sessions use Bearer JWT tokens obtained from the login flow. Pass the token in the Authorization header.

Using a JWT token

curl https://merx.exchange/api/v1/balance \
  -H "Authorization: Bearer eyJhbGciOi..."

Creating API Keys

POST/api/v1/keysRequires authentication

Create a new API key with specific permissions. The secret key is returned once and cannot be retrieved again.

Request body

namestringREQUIRED

A label for the key

permissionsstring[]REQUIRED

List of granted permissionsOne of: create_ordersview_ordersview_balancebroadcast

201Key created

{
  "id": "key_abc123",
  "name": "Production Bot",
  "key": "sk_live_a1b2c3d4e5f6...",
  "permissions": ["create_orders", "view_orders", "view_balance"],
  "created_at": "2026-03-29T10:00:00Z"
}

STORE YOUR KEY

The full key is shown only once at creation time. Store it in a secure secrets manager. If lost, revoke and create a new one.

Permissions

Permission	Grants access to
create_orders	POST /orders
view_orders	GET /orders, GET /orders/:id
view_balance	GET /balance, GET /history
broadcast	POST /broadcast

Rate Limits

Rate limits are applied per IP address. When exceeded, the API returns a 429 status with a Retry-After header.

Endpoint group	Limit
GET /prices, /prices/best, /prices/history, /prices/stats	300 req/min
GET /balance	60 req/min
GET /history, /history/summary	60 req/min
POST /orders, GET /orders	10 req/min
POST /withdraw	5 req/min
All other endpoints	100 req/min

Commission

Merx charges 0% commission for early adopters. You pay only the provider energy price. No subscription, no minimum, no withdrawal fees. The total_fee_sun field in order responses will show the fee amount (currently 0).

Security Best Practices

Never expose API keys in client-side code or public repositories
Use the minimum set of permissions required for each key
Rotate keys periodically and revoke unused ones
Store keys in environment variables or a secrets manager
Use separate keys for development and production