API Keys

API keys allow bots and external applications to access your ZDEX account without wallet signatures.

Permissions

Each API key has one or more permission scopes:

Permission	Access
`READ_ONLY`	View balances, positions, orders, market data
`TRADE`	Place and cancel orders, close positions
`WITHDRAW`	Full access including withdrawals

Create API Key

POST /v1/api-keys
Authorization: Bearer <token>
Content-Type: application/json

{
  "label": "My Trading Bot",
  "permissions": ["READ_ONLY", "TRADE"],
  "ipWhitelist": ["203.0.113.50"]
}

Parameters:

Field	Type	Required	Description
`label`	string	Yes	A descriptive name (max 50 chars)
`permissions`	string[]	No	Array of permissions. Default: `["READ_ONLY"]`
`ipWhitelist`	string[]	No	Restrict to specific IPs. Empty = all IPs allowed

Response:

{
  "ok": true,
  "id": "clx...",
  "apiKey": "zdex_a1b2c3d4e5f6789...",
  "secretKey": "e8f2a1b3c4d5e6f7890abcdef...",
  "label": "My Trading Bot",
  "permissions": ["READ_ONLY", "TRADE"],
  "message": "Save your secret key now. It will not be shown again."
}

Important: The secretKey is only returned once at creation time. Store it securely. If lost, revoke the key and create a new one.

List API Keys

GET /v1/api-keys
Authorization: Bearer <token>

Response:

{
  "ok": true,
  "keys": [
    {
      "id": "clx...",
      "label": "My Trading Bot",
      "keyPrefix": "zdex_a1b2c3d4",
      "permissions": ["READ_ONLY", "TRADE"],
      "ipWhitelist": ["203.0.113.50"],
      "isActive": true,
      "lastUsedAt": "2026-03-27T10:30:00.000Z",
      "createdAt": "2026-03-25T08:00:00.000Z"
    }
  ]
}

Update API Key

PATCH /v1/api-keys/:id
Authorization: Bearer <token>
Content-Type: application/json

{
  "label": "Updated Name",
  "permissions": ["READ_ONLY"],
  "ipWhitelist": []
}

All fields are optional. Only provided fields are updated.

Revoke API Key

DELETE /v1/api-keys/:id
Authorization: Bearer <token>

Revoked keys are permanently deactivated and cannot be restored.

Limits

Maximum 5 active API keys per account
Keys can optionally have an expiration date