License
Welcome to the Integral REST API reference.
Our REST API is for less latency-sensitive participants and has resource-oriented URLs, accepts JSON-encoded requests, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Contact Integral’s account management team to get connection details and credentials for access.
You can choose between two authentication methods:
An ID and password will be issued to you to generate and refresh/renew an access token. All REST API calls should pass this token to access authenticated services.
Users should use /v2/sso/login to get an access token. The access token is in SSO_TOKEN of the response header. Your token is valid for a limited time.
To keep your session alive, you can renew your token with /sso/tokens/renew. If your token is expired, you are issued a new token.
In this authentication method, you must sign each API request with a 'secret'. The 'secret' and 'userId' are issued to you during set up.
All REST requests must contain following header information:
| Header attribute | Description |
|---|---|
| Authorization | The base64-encoded signature. |
| Date | A date and time as standard UTC string. |
| Digest | SHA-256=base64(sha256(<body>)) If there is no request body, Digest should be set to the digest of a body of 0 length. |
| type | Set to hmac. |
You must send an authorization header with the following parameterization:
credentials := "hmac" params
params := userId "," algorithm ", " headers ", " signature
userId := "username" "=" plain-string
algorithm := "algorithm" "=" DQUOTE (hmac-sha256) DQUOTE
headers := "headers" "=" plain-string
signature := "signature" "=" plain-string
plain-string = DQUOTE *( %x20-21 / %x23-5B / %x5D-7E ) DQUOTE| Parameter | Description |
|---|---|
username | The ID of the credential. |
algorithm | Digital signature algorithm used to create the signature. You should use hmac-sha256. |
headers | List of HTTP header names, separated by a single space character, used to sign the request. |
signature | Base64 encoded digital signature generated by the client. |
To generate the string that is signed with a secret, the client must take the values of each HTTP header specified by headers in the order they appear.
request-line, then append the lowercase header name followed with an ASCII colon : and an ASCII space ' '.request-line, then append the HTTP request line (in ASCII format), otherwise append the header value.\n. The string must not include a trailing ASCII newline.You can set X-Request-ID on the request's HTTP header to trace each API call. The system echos back this header in the response.
All Integral REST APIs use the following general status codes. See endpoints for specific codes.
| HTTP code | HTTP status | Meaning |
|---|---|---|
| 200 | OK | Successful submission. |
| 202 | ACCEPTED | Request accepted by the system. You are expected to make another API call. Refer to individual API sections and endpoints for subsequent action. |
| 400 | BAD REQUEST | There is an issue with request parameters. May have a message body that indicates the error. Refer to individual API sections and endpoints for specific errors. |
| 401 | UNAUTHORIZED | Your IntegralAPI user is not authorized. May have a message body that indicates the error. |
| 404 | NOT FOUND | The endpoint could not be found. Either your valid request did not return any results or your request was malformed. May have a message body that indicates the error. Refer to individual API endpoints to confirm that the endpoint URL and parameters are correct. |
| 500 | INTERNAL SERVER ERROR | Stop trading immediately and contact Integral Business Support with a complete error message and full details of the HTTP request and response. May have a message body that indicates the error. |
4xx and 5xx status codes may return a JSON response body with the message parameter.
You determine the status of any call with a combination of:
200 and 404).Use the following codes to interpret and act on status responses.
| Reason code | Description |
|---|---|
RequestValidationError.amount | Order size is invalid. |
RequestValidationError.CoIdNotSpecified | Client order ID not specified. |
RequestValidationError.DuplicateOrder | Order already exists for the given client order ID. |
RequestValidationError.TypeNotSpecified | Order type not specified. |
RequestValidationError.TIFNotSpecified | Time in force not specified. |
RequestValidationError.SideNotSpecified | Order side (buy or sell) not specified. |
RequestValidationError.CurrencyNotSpecified | Order dealt currency not specified. |
RequestValidationError.InvalidDealtCcy | Dealt currency is neither base currency nor term currency. |
RequestValidationError.SymbolNotSpecified | Symbol not specified. |
RequestValidationError.InvalidCurrencyPair | Symbol not valid or not supported by the system. |
RequestValidationError.SizeNotSpecified | Order size not specified. |
RequestValidationError.InvalidOrderQty | Order size not valid. |
RequestValidationError.InvalidPrice | Accepted price invalid. Zero is invalid price. |
RequestValidationError.BuySellMismatch | Buy/Sell side of the accepted price is incorrect. |
RequestValidationError.InvalidQuoteID | The rateId of the previously quoted (PQ) order is invalid. |
RequestValidationError.LegalEntitySetIncorrectly | Account field incorrect. |
RequestValidationError.OrderTypeNotSupported | Order type not supported. |
RequestValidationError.PriceMismatch | Accepted price not the same as previously quoted price. |
RequestValidationError.QuoteExpired | Rate associated with the rateId not found. It has expired. Price is no longer valid. |
RequestValidationError.tradingDisabled | Trading is disabled. |
https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/
Place a new order. You can place various types of order such as limit, market, at best, previously quoted, stop, algo, pegged, and more. Under algo orders you can execute various strategies such as TWAP.
Returns status code 202 if your order is accepted by the system for processing. Use the query order endpoints to get the current status of your order Query order (client ID or all active orders) or Query order (server ID).
You can get all trades associated with an order using Query all trades on an order by ID. Trades contain information like counterparty, settlement date, and amount.
All place-order requests must have the following attributes:
coIdtypesidesymbolsizecurrencyYour request may require additional attributes based on the order type or attribute values.
For example, if you place an order with timeInForce=GTT (good-til-canceled) you must also specify expiryTime.
| Order type | Required attributes and values |
|---|---|
| Limit(IOC) | type=Limit, timeInForce=IOC, price |
| Limit(GTC) | type=Limit, timeInForce=GTC, price |
| Limit(GTT) | type=Limit, timeInForce=GTT, expiryTime, price |
| Market(IOC) | type=Market, timeInForce=IOC, price |
| At best | type=AtBest, timeInForce=FOK, valueDate |
| Stop | type=Stop, price, stopPrice, execFlags=BidTrigger|OfferTrigger|MidTrigger |
| Previously quoted | type=PQ, timeInForce=FOK, price, rateId |
| Algo (TWAP) | type=Algo, timeInForce=GTC, targetStrategy |
| On behalf of | price, org, account |
Buy or Sell from the order placer’s perspective and always for the dealt currency.
Base and term currency separated by a slash / (for example EUR/USD).
GTCIOCFOK (required for at-best orders)GTT (must specify expiryTime)DAYOrganization ID in Integral's system. If the order iss placed on behalf of another organization, this parameter contains the other organization's ID.
The ID of the account (legal entity) for which the order iss placed. Required when placing orders on behalf of another organization.
Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).
Execution strategy requested with order:
BidTrigger: Stay on bid sideMidTrigger: Mid priceOfferTrigger: Stay on offer sideAmount of the order visible to other market participants:
size: Display: Full order amount visible to other customers.size: Iceberg: Only the value of maxShow visible.(Algo) The algo or strategy of the order:
MidFixingTwapLitSwitchDarkSwitch(Algo) Relative time at which the strategy should start execution specified in the format HH:MM:SS.sss. If not specified, the strategy starts executing immediately.
(Algo) Absolute time in GMT at which the strategy should stop executing. If not specified, the order expires based on the value of its time in force.
The amount in pips that is added to the price of the peg. Can be positive or negative.
(Algo) Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap
(Algo) Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides passiveTimeFactor.
(Algo) Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if passiveTime is not set
(Algo) Interval between slices in milliseconds. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values.
(Algo) The percentage range that the sliceSize is randomized.
(Algo) The percentage range that the sliceInterval is randomized.
https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/v2/orders
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/v2/orders
{ "coId": "8932452311944", "type": "Limit", "side": "Buy", "symbol": "EUR/USD", "currency": "EUR", "size": 1000000, "price": 1.0971678, "timeInForce": "IOC" }
orderId assigned by the system.Buy or Sell from the order placer’s perspective and always for the dealt currency.
Base and term currency separated by a slash / (for example EUR/USD).
Organization ID in Integral's system. If the order was placed on behalf of another organization, this parameter contains the other organization's ID.
The ID of the account (legal entity) for which the order was placed. Required when placing orders on behalf of another organization.
Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).
Time the order was submitted in the format yyyy-MM-dd HH:mm:ss,SSS Z.
Algo: The algo or strategy of the order:
MidFixingTwapLitSwitchDarkSwitchThe original client order ID of the order to be cancelled or replaced by this request.
Execution strategy requested with order:
BidTrigger: Stay on bid sideMidTrigger: Mid priceOfferTrigger: Stay on offer sideAmount of the order visible to other market participants:
size: Display: Full order amount visible to other customers.size: Iceberg: Only the value of maxShow visible.Average price of all fills so far. For orders and order types with timeInForce=FOK such as at-best orders, this is the filled price.
Fully qualified user name of order submitting user, including namespace and organization ID in the format userName@namespace.orgID.
RECEIVED: Order received.NEW: Order has been entered and is working according to the order type and specified execution strategy.PARTIALLY_FILLED: Trade done that does not completely fill the order.FILLED: Trade done that completely fills the order.PENDING_CANCEL: Cancel order request has been received and is in process.CANCELED: Order has been canceled.REPLACED: Order has been replaced with a new order.STOPPED: Price matching has been paused for the order.REJECTED: Order has been rejected.EXPIRED: Order expired.FAILED: Order failed.Orders with status=FAILED or status=REJECTED, the reason for failure or rejection. INTERNAL_SERVER_ERROR indicates a serious error. Stop trading immediately and contact Business Support to resolve the issue.
Relative time at which the strategy should start execution specified in the format HH:MM:SS.sss. If not specified, the strategy starts executing immediately.
Absolute time in GMT at which the strategy should stop executing. If not specified, the order expires based on the value of its time in force.
The amount in pips that is added to the price of the peg. Can be positive or negative.
Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap
Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides passiveTimeFactor.
Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if passiveTime is not set
Interval between slices in milliseconds. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values.
The percentage range that the sliceInterval is randomized.
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" }
https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/v2/orders
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/v2/orders
No request payloadAn array of orders that match the request.
Buy or Sell from the order placer’s perspective and always for the dealt currency.
Base and term currency separated by a slash / (for example EUR/USD).
Organization ID in Integral's system. If the order was placed on behalf of another organization, this parameter contains the other organization's ID.
The ID of the account (legal entity) for which the order was placed. Required when placing orders on behalf of another organization.
Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).
Time the order was submitted in the format yyyy-MM-dd HH:mm:ss,SSS Z.
Algo: The algo or strategy of the order:
MidFixingTwapLitSwitchDarkSwitchThe original client order ID of the order to be cancelled or replaced by this request.
Execution strategy requested with order:
BidTrigger: Stay on bid sideMidTrigger: Mid priceOfferTrigger: Stay on offer sideAmount of the order visible to other market participants:
size: Display: Full order amount visible to other customers.size: Iceberg: Only the value of maxShow visible.Average price of all fills so far. For orders and order types with timeInForce=FOK such as at-best orders, this is the filled price.
Fully qualified user name of order submitting user, including namespace and organization ID in the format userName@namespace.orgID.
RECEIVED: Order received.NEW: Order has been entered and is working according to the order type and specified execution strategy.PARTIALLY_FILLED: Trade done that does not completely fill the order.FILLED: Trade done that completely fills the order.PENDING_CANCEL: Cancel order request has been received and is in process.CANCELED: Order has been canceled.REPLACED: Order has been replaced with a new order.STOPPED: Price matching has been paused for the order.REJECTED: Order has been rejected.EXPIRED: Order expired.FAILED: Order failed.Orders with status=FAILED or status=REJECTED, the reason for failure or rejection. INTERNAL_SERVER_ERROR indicates a serious error. Stop trading immediately and contact Business Support to resolve the issue.
Relative time at which the strategy should start execution specified in the format HH:MM:SS.sss. If not specified, the strategy starts executing immediately.
Absolute time in GMT at which the strategy should stop executing. If not specified, the order expires based on the value of its time in force.
The amount in pips that is added to the price of the peg. Can be positive or negative.
Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap
Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides passiveTimeFactor.
Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if passiveTime is not set
Interval between slices in milliseconds. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values.
The percentage range that the sliceInterval is randomized.
If sliceSize undefined, the slice size is this percentage of the top-of-book price size.
A single order, either by coId or the only active order.
[ { "coId": "Order25", "type": "Limit", "timeInForce": "DAY", "side": "Buy", "currency": "EUR", "symbol": "EUR/USD", "size": 1000000, "org": "pfOrg", "account": "pfOrgLE", "price": 1.1993, "actionOnExpiry": "NoAction", "averagePrice": 0, "cumQty": 0, "orderId": "4860875001", "tradeDate": "2022-10-11", "userFullName": "user1@pfgOrg", "action": "place", "status": "NEW" } ]
With best effort, cancel all active orders. This may require you to make the request multiple times until all of the open active orders are cancelled. You can call Query order (client ID or all active orders) to check if any order is still active.
https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/v2/orders
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/v2/orders
No request payloadhttps://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/v2/orders/{id}
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/v2/orders/{id}
No request payloadThe order that matches the given id.
Buy or Sell from the order placer’s perspective and always for the dealt currency.
Base and term currency separated by a slash / (for example EUR/USD).
Organization ID in Integral's system. If the order was placed on behalf of another organization, this parameter contains the other organization's ID.
The ID of the account (legal entity) for which the order was placed. Required when placing orders on behalf of another organization.
Expiry time when timeInForce=GTT. In seconds. Max value is one day (86399 seconds).
Time the order was submitted in the format yyyy-MM-dd HH:mm:ss,SSS Z.
Algo: The algo or strategy of the order:
MidFixingTwapLitSwitchDarkSwitchThe original client order ID of the order to be cancelled or replaced by this request.
Execution strategy requested with order:
BidTrigger: Stay on bid sideMidTrigger: Mid priceOfferTrigger: Stay on offer sideAmount of the order visible to other market participants:
size: Display: Full order amount visible to other customers.size: Iceberg: Only the value of maxShow visible.Average price of all fills so far. For orders and order types with timeInForce=FOK such as at-best orders, this is the filled price.
Fully qualified user name of order submitting user, including namespace and organization ID in the format userName@namespace.orgID.
RECEIVED: Order received.NEW: Order has been entered and is working according to the order type and specified execution strategy.PARTIALLY_FILLED: Trade done that does not completely fill the order.FILLED: Trade done that completely fills the order.PENDING_CANCEL: Cancel order request has been received and is in process.CANCELED: Order has been canceled.REPLACED: Order has been replaced with a new order.STOPPED: Price matching has been paused for the order.REJECTED: Order has been rejected.EXPIRED: Order expired.FAILED: Order failed.Orders with status=FAILED or status=REJECTED, the reason for failure or rejection. INTERNAL_SERVER_ERROR indicates a serious error. Stop trading immediately and contact Business Support to resolve the issue.
Relative time at which the strategy should start execution specified in the format HH:MM:SS.sss. If not specified, the strategy starts executing immediately.
Absolute time in GMT at which the strategy should stop executing. If not specified, the order expires based on the value of its time in force.
The amount in pips that is added to the price of the peg. Can be positive or negative.
Action taken at the end of the algo’s duration if there is an unfilled amount remaining. If not specified, the order is cancelled at expiration. NoAction, FillAtMarket, Twap
Time for which each slice rests in OCX RiskNet. Specified in milliseconds. Overrides passiveTimeFactor.
Determines how long each slice rests in OCX RiskNet, calculated as a percent of the actual slice interval. Required if passiveTime is not set
Interval between slices in milliseconds. If the interval is fixed, this value is the interval duration. If the interval is randomized, this value is the upper boundary of random values.
The percentage range that the sliceInterval is randomized.
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" }
Cancel a single active order by ID (the unique ID assigned by server, received in the place order response). Use Query order (server ID) or Query order (client ID or all active orders) to get the current status of your order.
https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/v2/orders/{id}
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/v2/orders/{id}
No request payloadThe RFS/RFQ endpoints provide API access to two trading workflows:
You receive responses against your RFS and RFQ requests using the Query request response API and can choose to either accept the quote, withdraw your quote request, or you can allow the your request or quote to expire.
Request for Stream (RFS) workflow:
Request for Quote (RFQ) workflow:
Get executed trades that have not been downloaded before.
To get trades that have been previously downloaded, you must first call the Prepare trades to resend endpoint.