Buy

Trading

Auth Required

Purchase a contract. The loginid parameter has been removed and buy field validation relaxed.

3 breaking changes - code updates required

Critical Change:

The loginid parameter has been removed. Multi-account users must update their requests.

Quick comparison

Aspect	Legacy	New	Action required
Endpoint ✅ Same	buy	buy	None
Auth Required ✅ Same	Yes	Yes	None
loginid Parameter ❌ Removed	Optional	Removed	Remove from requests
buy Field Pattern ⚠️ Changed	Strict (32-128 chars)	Relaxed	Review validation
subscribe Parameter ⚠️ Changed	enum [1]	enum [0, 1]	None (backward compatible)

Breaking changes

1. loginid parameter removed

What Changed: The loginid parameter has been removed in New. This parameter was previously used for multi-account authentication.

Migration: Remove the loginid field from your buy requests. Account selection is now handled through the authorization token.

2. buy field validation relaxed

What Changed: The buy field no longer enforces the strict pattern ^(?:[\w-]{32,128}|1)$.

Migration: If you have client-side validation matching the legacy pattern, you may relax it. Server-side validation still ensures valid proposal IDs.

3. buy object now required in response

What Changed: The buy object is now a required field in the response. In Legacy, only echo_req andmsg_type were required at the root level.

Migration: Update error handling to expect the buy object to always be present in successful responses.

Additional changes

subscribe parameter extended

The subscribe parameter now accepts0 in addition to 1. This allows explicitly disabling subscription. This change is backward compatible.

Request structure

Legacy Request Example

1{
2  "buy": "uw2mk7no3oktoRVVsB4Dz7TQnFfAB",
3  "price": 10.50,
4  "loginid": "CR123456"
5}

New Request Example

1{
2  "buy": "uw2mk7no3oktoRVVsB4Dz7TQnFfAB",
3  "price": 10.50
4}

Note: The loginid parameter must be removed in New.

Response structure

Legacy Response Example

1{
2  "buy": {
3    "balance_after": 9989.50,
4    "buy_price": 10.50,
5    "contract_id": 123456789,
6    "longcode": "Win payout if Volatility 100 Index is strictly higher than entry spot at 5 minutes after contract start time.",
7    "payout": 20.00,
8    "purchase_time": 1234567890,
9    "shortcode": "CALL_R_100_20_1234567890_1234568190_S0P_0",
10    "start_time": 1234567890,
11    "transaction_id": 987654321
12  },
13  "echo_req": { "buy": "uw2mk7no3oktoRVVsB4Dz7TQnFfAB", "price": 10.50 },
14  "msg_type": "buy"
15}

New Response Example

1{
2  "buy": {
3    "balance_after": 9989.50,
4    "buy_price": 10.50,
5    "contract_id": 123456789,
6    "longcode": "Win payout if Volatility 100 Index is strictly higher than entry spot at 5 minutes after contract start time.",
7    "payout": 20.00,
8    "purchase_time": 1234567890,
9    "shortcode": "CALL_R_100_20_1234567890_1234568190_S0P_0",
10    "start_time": 1234567890,
11    "transaction_id": 987654321
12  },
13  "echo_req": { "buy": "uw2mk7no3oktoRVVsB4Dz7TQnFfAB", "price": 10.50 },
14  "msg_type": "buy"
15}

Note: Response structure is identical, but the buy object is now required (was optional at root level in Legacy).

Code examples

Legacy Implementation

1async function buyContract(proposalId, price, loginid) {
2  const request = {
3    buy: proposalId,
4    price: price,
5    // loginid used for multi-account support
6    loginid: loginid
7  };
8
9  ws.send(JSON.stringify(request));
10
11  ws.onmessage = (event) => {
12    const response = JSON.parse(event.data);
13    if (response.msg_type === 'buy') {
14      // buy object may be missing in some cases
15      if (response.buy) {
16        console.log('Contract ID:', response.buy.contract_id);
17        console.log('Balance After:', response.buy.balance_after);
18        console.log('Shortcode:', response.buy.shortcode);
19      }
20    }
21  };
22}

New Implementation

1async function buyContract(proposalId, price) {
2  const request = {
3    buy: proposalId,
4    price: price
5    // loginid removed - account selection via auth token
6  };
7
8  ws.send(JSON.stringify(request));
9
10  ws.onmessage = (event) => {
11    const response = JSON.parse(event.data);
12    if (response.msg_type === 'buy') {
13      // buy object is always present in successful responses
14      console.log('Contract ID:', response.buy.contract_id);
15      console.log('Balance After:', response.buy.balance_after);
16      console.log('Shortcode:', response.buy.shortcode);
17    }
18  };
19}

Migration checklist

☐

Remove loginid parameter

Remove the loginid field from all buy requests

☐

Update client-side validation

Relax buy field validation if using the legacy pattern

☐

Review response handling

The buy object is now guaranteed in successful responses

Balance Cancel