Cookbook
/
REST
/
Full workflows
/
Trade on behalf of another organization

Trade on behalf of

Goal

Execute a spot trade with ESP rates on behalf of another organization, from login and requesting rates to downloading the done trade.

This guide uses the Get fixed-period market data workflow for tradable rates, but you can substitute the Get spot prices workflow in Step 2.

Prerequisites

  • Your REST API app.
  • Integral API login with trading permission.
  • Your organization provisioned with at least one provider who streams ESP spot prices.
  • A customer organization that you trade on behalf of.

Steps

Poll for order status
Order status = FILLED
Step 1: Login
Step 2: Get market data
Step 3: Place order (previously quoted)
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.

Use the rateId attribute of the JSON response in the next step.

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 an order (previously quoted)

Use the Place order endpoint.

See the related Place an order (previously quoted) tutorial.

These parameters are required on the request body: org, account, coId, type, side, symbol, size, price, currency, timeInForce, rateId.

  • rateId contains the rateId from the rate in the market data.
  • org contains the organization ID of the organization you are trading on behalf of.
  • account contains the account ID (legal entity) of the behalf-of organization.

To get your order status, you must query your order. After the initial success/fail response to your request, 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
No request payload
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 array 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