Cookbook
/
REST
/
Full workflows
/
Trade fixed-period rates

Trade fixed-period rates

Goal

Execute a trade with rates from a fixed-period market data set, from login and requesting rates to downloading the done trade.

Prerequisites

  • Your REST API app.
  • Integral API login with trading permission.
  • Your organization provisioned with at least one provider who supports fixed-period market data sets.

Steps

Poll for order status
Order status = FILLED
Step 1: Login
Step 2: Get fixed-period market data
Step 3: Place order
Step 4: Query order
Step 5: Download trade

Step 1: Login

Use the Login and get token endpoint.

See the related Login tutorial.

Your access token is in SSO_TOKEN of the response header. Your token is valid for limited time.

Pass the SSO_TOKEN cookie value with all of your subsequent API requests.

application/json
{
  "user": "apiUserId",
  "pass": "This is a long password!",
  "org": "apiOrganizationId"
}
Response
application/json
{
  "status": "OK",
  "errorCode": null,
  "responseTuples": null,
  "expiryTime": 1665490480729,
  "serverUTCTime": 1665490420730
}

Step 2: Get fixed-period market data

Use the Get market data endpoint.

See the related Get fixed-period market data tutorial.

const query = new URLSearchParams({
  id: 'string',
  org: 'BNK1-4HOrg',
  symbol: 'EUR/USD',
  symbols: 'EUR/USD,USD/JPY',
  date: '2024-10-24',
  tenor: 'SPOT',
  timeWindow: '1500-1700'
}).toString();

const resp = await fetch(
  `https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/marketdataset?${query}`,
  {
    method: 'GET',
    headers: {
      SSO_TOKEN: 'YOUR_API_KEY_HERE'
    }
  }
);

const data = await resp.text();
console.log(data);
Response
application/json
[
  {
    "id": "RealTimeMDS",
    "date": null,
    "timeWindow": null,
    "name": "Real-time market data",
    "createdTime": null,
    "activationTime": null,
    "validUntil": null,
    "nextCreationTime": null,
    "expirationTime": null,
    "rates": [ … ]
  }
]

Step 3: Place order

Use the Place order endpoint.

Send the rateId of the rate from the market data set in the rateId parameter of the request body.

To get your order status, you must query your order. After the initial success/fail response, status updates are not pushed to you.

Response
application/json

Successful limit order

{
  "coId": "8932452311944",
  "type": "Limit",
  "timeInForce": "IOC",
  "side": "Buy",
  "currency": "EUR",
  "symbol": "EUR/USD",
  "size": 1000000,
  "org": "BrokerOrg1",
  "price": 1.0971678,
  "orderId": "4820276016",
  "userFullName": "User1@pfOrg",
  "action": "place",
  "status": "RECEIVED"
}

Step 4: Query order

To get your order status, you must query your order. After the initial success/fail response, status updates are not pushed to you.

Use the Query order (server ID) endpoint.

The diagram shows the values returned in the status field in the response.

Order status transition (PQ order, success)
Place order
Query order
Query order
Query order
Query order
Status = RECEIVED
HTTP code 202
Status = NEW
(Intermediate state)
HTTP code 200
Status = FILLED
HTTP code 200
Status = REJECTED
HTTP code 200
Order status transition (failure)
Place order
Error object
HTTP code 400/5xx
const id = '4820276016';
const resp = await fetch(
  `https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/v2/orders/${id}`,
  {
    method: 'GET',
    headers: {
      SSO_TOKEN: 'YOUR_API_KEY_HERE'
    }
  }
);

const data = await resp.text();
console.log(data);
Response
application/json

Successful limit order

{
  "coId": "8932452311944",
  "type": "Limit",
  "timeInForce": "IOC",
  "side": "Buy",
  "currency": "EUR",
  "symbol": "EUR/USD",
  "size": 1000000,
  "org": "BrokerOrg1",
  "price": 1.0971678,
  "orderId": "4820276016",
  "userFullName": "User1@pfOrg",
  "action": "place",
  "status": "RECEIVED"
}

Step 5: Download trade

Use the Get trades endpoint.

The endpoint returns all executed trades that have not been downloaded before.

Use the orderId from the 202 response when you placed the order to find your trade in the list of returned trades.

No request payload
Response
application/json

STP download of trade to fill limit order request

[
  {
    "orderId": "4820276016",
    "tradeId": "FXI9369258100",
    "tradeType": "Spot",
    "tradeDate": "2023-06-02",
    "valueDate": "2023-06-15",
    "maker": false,
    "side": "Buy",
    "status": "Verified",
    "symbol": "EUR/USD",
    "currency": "EUR",
    "customerAccount": "CustomerOrgle1",
    "customerOrg": "CustomerOrg",
    "user": "userName@CustomerOrg",
    "counterparty": "BrokerOrg1",
    "counterpartyLongName": "The Broker Org",
    "counterpartyAccount": "BrokerOrg1LE5",
    "coId": "8932452311944",
    "channel": "API/REST/ESP",
    "executionTime": "2023-06-02 18:31:01,301 +0000",
    "dealtAmount": 1000000,
    "settledAmount": 1097166.9,
    "baseAmount": 1000000,
    "termAmount": 1097166.9,
    "spotRate": 1.0971669,
    "rate": 1.0971669,
    "event": "NEW",
    "channelCategory": "API",
    "upi": "EUR_USD_SPOT",
    "uti": "1234567890AQUSUUINP9349138130"
  }
]
Previous page
Next page