API

Authentication

All endpoints require authentication via one of:

• Header: X-API-Key: <your_api_key>
• Header: Authorization: Bearer <your_api_key>

Set the API key via the API_Key plugin parameter in MT5 Administrator. Leave API_Key empty to disable the API entirely.

Base URL

http://<server_ip>:<API_Port>/api/

Default port: 8447

GET/api/status

Returns plugin status and daily statistics.

{
  "plugin": "Brokeret Bonus Manager",
  "version": "1.00",
  "license_active": true,
  "campaigns_total": 3,
  "bonuses_total": 45,
  "stats": {
    "granted": 12,
    "removed": 3,
    "converted": 2,
    "expired": 1,
    "drawdown": 0,
    "credit_granted": 15000.00,
    "credit_removed": 3500.00,
    "credit_converted": 2000.00
  }
}

GET/api/campaigns

Lists all campaigns.

{
  "campaigns": [
    {
      "campaign_id": 1,
      "name": "Summer 30%",
      "status": 1,
      "bonus_type": 0,
      "bonus_percentage": 30.00,
      "max_bonus_amount": 5000.00,
      "min_deposit": 100.00,
      "max_deposit": 0.00,
      "withdrawal_mode": 1,
      "lots_required": 0.00,
      "lot_scope": 0,
      "symbol_filter": "*",
      "per_trade_min_lots": 0.00,
      "expiry_days": 30,
      "group_mask": "real\\*",
      "one_per_account": true,
      "max_concurrent": 3,
      "drawdown_mode": 2
    }
  ],
  "total": 1
}

POST/api/campaigns

Create a new campaign.

Request Body

{
  "name": "Summer 30%",
  "group_mask": "real\\*",
  "bonus_type": 0,
  "bonus_percentage": 30.0,
  "max_bonus_amount": 5000.0,
  "min_deposit": 100.0,
  "max_deposit": 0,
  "withdrawal_mode": 1,
  "expiry_days": 30,
  "one_per_account": true,
  "max_concurrent": 3,
  "drawdown_mode": 2
}

Required fields: name, group_mask, bonus_percentage

See the Parameters page for all available campaign fields and their defaults.

Response (201)

{
  "success": true,
  "campaign_id": 1
}

PUT/api/campaigns/{id}

Update an existing campaign. Only include fields you want to change.

Request Body

{
  "status": 0,
  "bonus_percentage": 25.0
}

Response (200)

{
  "success": true,
  "campaign_id": 1
}

DELETE/api/campaigns/{id}

Delete a campaign.

{
  "success": true
}

GET/api/bonuses

List bonuses with optional filters.

Query parameters:

• ?login=<login> — Filter by MT5 login
• ?status=<status> — Filter by status: 0 = active, 1 = converted, 2 = expired, 3 = removed, 4 = revoked, 5 = drawdown
• ?campaign_id=<id> — Filter by campaign

Response

{
  "bonuses": [
    {
      "bonus_id": 7,
      "login": 12345,
      "campaign_id": 1,
      "deposit_deal_id": 98765,
      "credit_deal_id": 98766,
      "amount": 300.00,
      "amount_converted": 150.00,
      "lots_required": 10.00,
      "lots_traded": 5.00,
      "granted_time": 1709568000,
      "expiry_time": 1712160000,
      "status": 0
    }
  ],
  "total": 1
}

GET/api/bonuses/{id}

Get a single bonus by ID.

Returns the same bonus object structure as above.

POST/api/bonuses/grant

Manually grant a bonus (bypasses the deposit trigger).

Request Body

{
  "login": 12345,
  "campaign_id": 1,
  "amount": 500.00
}

Required fields: login, campaign_id, amount

Response (201)

{
  "success": true
}

DELETE/api/bonuses/{id}

Manually revoke an active bonus. Removes remaining credit from the MT5 account.

{
  "success": true
}

GET/api/log

Activity log (ring buffer, last 500 entries).

Query parameters:

• ?login=<login> — Filter by MT5 login

Response

{
  "log": [
    {
      "timestamp": 1709568000,
      "login": 12345,
      "bonus_id": 7,
      "campaign_id": 1,
      "action": "GRANT",
      "amount": 300.00,
      "detail": "30% of $1000.00 deposit, campaign='Summer 30%'"
    }
  ],
  "count": 1
}

Action types: GRANT, REMOVE, REDUCE, CONVERT, CONVERTED, EXPIRED, DRAWDOWN, REVOKE, CLEANUP

GET/api/stats

Daily statistics (resets at midnight UTC).

{
  "date": 20260304,
  "bonuses_granted": 12,
  "bonuses_removed": 3,
  "bonuses_converted": 2,
  "bonuses_expired": 1,
  "bonuses_drawdown": 0,
  "total_credit_granted": 15000.00,
  "total_credit_removed": 3500.00,
  "total_credit_converted": 2000.00
}

Error Responses

All errors return JSON:

{
  "error": "description of the error"
}