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.
Authentication options
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.
Get token
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.
Pass token
The token should be sent in SSO_TOKEN of request headers.
Renew token
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.
HMAC authentication
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:
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.
If the header name is not request-line, then append the lowercase header name followed with an ASCII colon : and an ASCII space ' '.
If the header name is request-line, then append the HTTP request line (in ASCII format), otherwise append the header value.
If the value is not the last value, then append an ASCII newline \n. The string must not include a trailing ASCII newline.
API tracing
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.
Status and error codes
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.
Reason codes
You determine the status of any call with a combination of:
Status code from the messaging technology (for example, REST/HTTP codes 200 and 404).
The reason code for the server. Not all responses include a reason code.
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.
Endpoints to login with token-based authentication.
Operations
Market data
Endpoints to get prices, indicative rates, benchmark rates, and trade ticker rates.
Operations
Orders
Place, cancel, and query orders.
Operations
Trades
Trade operations (book, query, amend, roll, allocate, cancel). Also query orders for fills.
Only brokers and sales dealers can amend, roll, and allocate by default. Customer organizations can be configured to allocate trades (work with your Integral Technical Account Manager).
Operations
RFS/RFQ
The RFS/RFQ endpoints provides API access to two trading workflows:
Request for Stream (RFS): a stream of firm quotes from liquidity providers against your quote request for a symbol, tenor, amount, and direction for a given price type.
Request for Quote (RFQ): a single quote good for a duration you request. The server must be configured to enable the RFQ workflow. Please contact your Technical Account Manager to discuss settings.
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:
Send your request:
Set the symbol, tenor, amount, and buy/sell direction.
Base and term currency separated by a slash / (for example EUR/USD).
valueDatestring<= 20 characters
The value date of the trades that make up the position in the format YYYY=MM-DD.
levelstring<= 32 characters
No default value. The level at which the position is calculated:
USER: user
LE: legal entity
ORG: organization
levelValuestring<= 30 characters
The ID of either the user or organization based on the value of level.
netOpenBasenumber(double)
Net open amount in base currency.
netOpentermnumber(double)
Net open amount in term currency. Note the property name is not a typo ("term" is lowercase).
ratenumber(double)
The weighted average buy or sell rate of the current position.
realizedPnLnumber(double)
The profit or loss in the base currency determined by taking all trades (or portions thereof) that are closed and computing the profit for each pair of opposing buy/sell trades.
unrealizedPnLnumber(double)
The profit or loss in the base currency determined by taking the position's currency pair rate against the current market rate at the position amount. Essentially, the unrealized P/L is the profit or loss if the position was closed at the current close rate.
Get open positions by value date. All query parameters are optional. If no parameters are specified, all open positions for the logged-in user and specified value date are returned.
Path
valueDatestring<= 20 charactersrequired
No default value. Value date in the format YYYY-MM-DD.
Example: 2022-03-11
Query
symbolstring<= 35 characters
No default value. Base and term currency separated by a slash /.
Example: symbol=EUR/USD
levelstring<= 32 characters
No default value. The level at which the position is calculated, case sensitive:
USER: user
LE: legal entity
ORG: organization
Examples:
level=USER
level=LE
level=ORG
valuestring<= 30 characters
No default value. The ID of a specific org, legal entity, or user (depending on level).
Example: value=pfOrg
Mock server https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/v2/positions/{valueDate}
Base and term currency separated by a slash / (for example EUR/USD).
valueDatestring<= 20 characters
The value date of the trades that make up the position in the format YYYY=MM-DD.
levelstring<= 32 characters
No default value. The level at which the position is calculated:
USER: user
LE: legal entity
ORG: organization
levelValuestring<= 30 characters
The ID of either the user or organization based on the value of level.
netOpenBasenumber(double)
Net open amount in base currency.
netOpentermnumber(double)
Net open amount in term currency. Note the property name is not a typo ("term" is lowercase).
ratenumber(double)
The weighted average buy or sell rate of the current position.
realizedPnLnumber(double)
The profit or loss in the base currency determined by taking all trades (or portions thereof) that are closed and computing the profit for each pair of opposing buy/sell trades.
unrealizedPnLnumber(double)
The profit or loss in the base currency determined by taking the position's currency pair rate against the current market rate at the position amount. Essentially, the unrealized P/L is the profit or loss if the position was closed at the current close rate.