Sell

Trading

Auth Required

Sell an active contract before expiry to realize profit or minimize loss. The loginid parameter removed, price validation added, and response fields now guaranteed.

4 breaking changes - code updates required

Critical Changes:

The loginid parameter has been removed
The price parameter now requires minimum value of 0
The sell object is now required in response
All fields in sell object are now required

Quick comparison

Aspect	Legacy	New	Action required
Endpoint ✅ Same	sell	sell	None
Auth Required ✅ Same	Yes	Yes	None
Scope ✅ Same	trade	trade	None
loginid Parameter ❌ Removed	Optional	Removed	Remove from requests
price Validation ⚠️ Changed	No minimum	minimum: 0	Ensure non-negative
Response sell Object ⚠️ Changed	Optional	Required	Remove null checks
sell Object Fields ⚠️ Changed	All optional	All required	Update types

Breaking changes

1. Removed loginid parameter

What Changed: The loginid parameter that was used for multi-account scenarios has been removed in v4. Account context must now be established through the authorization flow rather than per-request parameters.

Migration: Remove the loginid parameter from your requests.

2. price parameter validation added

What Changed: The price parameter now has a minimum: 0 validation constraint. Negative values will be rejected.

Migration: Ensure you always pass a non-negative value for price. Use 0 for "sell at market".

3. sell object now required in response

What Changed: In legacy, the sell object was optional in the response. In v4, it is always present for successful sell operations.

Migration: You can simplify your code by removing null checks for the sell object.

4. All sell object fields now required

What Changed: All 5 fields inside the sell object are now guaranteed to be present:

balance_after - New account balance after sale
contract_id - Internal contract identifier
reference_id - Transaction ID of the original buy
sold_for - Actual sale price
transaction_id - Transaction ID of this sale

Migration: Update your TypeScript interfaces to mark these fields as required instead of optional.

Request structure

Legacy Request Example

1{
2  "sell": 11542203588,
3  "price": 500,
4  "loginid": "CR123456"
5}

New Request Example

1{
2  "sell": 11542203588,
3  "price": 500
4}

Note: The loginid parameter is removed. The price must be ≥ 0.

Response structure

Legacy Response Example

1{
2  "sell": {
3    "balance_after": 10500.50,
4    "contract_id": 11542203588,
5    "reference_id": 11542203587,
6    "sold_for": 750.25,
7    "transaction_id": 98765432
8  },
9  "echo_req": {
10    "sell": 11542203588,
11    "price": 500
12  },
13  "msg_type": "sell"
14}
15
16// Note: In v3, "sell" object and all its
17// fields were optional and could be absent

New Response Example

1{
2  "sell": {
3    "balance_after": 10500.50,
4    "contract_id": 11542203588,
5    "reference_id": 11542203587,
6    "sold_for": 750.25,
7    "transaction_id": 98765432
8  },
9  "echo_req": {
10    "sell": 11542203588,
11    "price": 500
12  },
13  "msg_type": "sell"
14}
15
16// Note: In v4, "sell" object and all its
17// fields are guaranteed to be present

Code examples

Legacy Implementation

1async function sellContract(contractId, minimumPrice, loginId) {
2  const request = {
3    sell: contractId,
4    price: minimumPrice,
5    loginid: loginId  // Optional for multi-account
6  };
7  
8  ws.send(JSON.stringify(request));
9  
10  ws.onmessage = (msg) => {
11    const response = JSON.parse(msg.data);
12    if (response.msg_type === 'sell') {
13      // Must check if sell object exists
14      if (response.sell) {
15        // Must check each field
16        const soldFor = response.sell.sold_for ?? 0;
17        const balance = response.sell.balance_after ?? 0;
18        console.log(`Sold for: ${soldFor}`);
19        console.log(`Balance: ${balance}`);
20      }
21    }
22  };
23}

New Implementation

1async function sellContract(contractId, minimumPrice) {
2  const request = {
3    sell: contractId,
4    price: minimumPrice  // Must be >= 0
5    // loginid no longer supported
6  };
7  
8  ws.send(JSON.stringify(request));
9  
10  ws.onmessage = (msg) => {
11    const response = JSON.parse(msg.data);
12    if (response.msg_type === 'sell') {
13      // sell object and fields guaranteed
14      const { sold_for, balance_after } = response.sell;
15      console.log(`Sold for: ${sold_for}`);
16      console.log(`Balance: ${balance_after}`);
17    }
18  };
19}

TypeScript types

Legacy Types

1interface SellRequest {
2  sell: number;
3  price: number;
4  loginid?: string;  // Optional
5  passthrough?: object;
6  req_id?: number;
7}
8
9interface SellResponse {
10  sell?: {  // Optional object
11    balance_after?: number;
12    contract_id?: number;
13    reference_id?: number;
14    sold_for?: number;
15    transaction_id?: number;
16  };
17  echo_req: object;
18  msg_type: 'sell';
19  req_id?: number;
20}

New Types

1interface SellRequest {
2  sell: number;
3  price: number;  // minimum: 0
4  // loginid removed
5  passthrough?: object;
6  req_id?: number;
7}
8
9interface SellResponse {
10  sell: {  // Required object
11    balance_after: number;   // Required
12    contract_id: number;     // Required
13    reference_id: number;    // Required
14    sold_for: number;        // Required
15    transaction_id: number;  // Required
16  };
17  echo_req: object;
18  msg_type: 'sell';
19  req_id?: number;
20}

Proposal open contract Statement