API reference
/
REST API
/
STP download
/
Get done trades

REST API (1.0.1)

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.

Authentication options

You can choose between two authentication methods:

Token-based authentication

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:

Header attribute Description
AuthorizationThe base64-encoded signature.
DateA date and time as standard UTC string.
DigestSHA-256=base64(sha256(<body>)) If there is no request body, Digest should be set to the digest of a body of 0 length.
typeSet 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

Signature parameters

Parameter Description
usernameThe ID of the credential.
algorithmDigital signature algorithm used to create the signature. You should use hmac-sha256.
headersList of HTTP header names, separated by a single space character, used to sign the request.
signatureBase64 encoded digital signature generated by the client.

Sample authorization header

Authorization: hmac userId="user2@XCN1139",
  algorithm="hmac-sha256",
  headers="date content-type content-length",
  signature="XWL1oxJsbC4z3UvO6ZfvgjMvfj249WXSb7Gl/+t/Ql0="

Signature string construction

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.

  1. If the header name is not request-line, then append the lowercase header name followed with an ASCII colon : and an ASCII space ' '.
  2. If the header name is request-line, then append the HTTP request line (in ASCII format), otherwise append the header value.
  3. 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 statusMeaning
200OKSuccessful submission.
202ACCEPTEDRequest accepted by the system. You are expected to make another API call. Refer to individual API sections and endpoints for subsequent action.
400BAD REQUESTThere 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.
401UNAUTHORIZEDYour IntegralAPI user is not authorized. May have a message body that indicates the error.
404NOT FOUNDThe 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.
500INTERNAL SERVER ERRORStop 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.amountOrder size is invalid.
RequestValidationError.CoIdNotSpecifiedClient order ID not specified.
RequestValidationError.DuplicateOrderOrder already exists for the given client order ID.
RequestValidationError.TypeNotSpecifiedOrder type not specified.
RequestValidationError.TIFNotSpecifiedTime in force not specified.
RequestValidationError.SideNotSpecifiedOrder side (buy or sell) not specified.
RequestValidationError.CurrencyNotSpecifiedOrder dealt currency not specified.
RequestValidationError.InvalidDealtCcyDealt currency is neither base currency nor term currency.
RequestValidationError.SymbolNotSpecifiedSymbol not specified.
RequestValidationError.InvalidCurrencyPairSymbol not valid or not supported by the system.
RequestValidationError.SizeNotSpecifiedOrder size not specified.
RequestValidationError.InvalidOrderQtyOrder size not valid.
RequestValidationError.InvalidPriceAccepted price invalid. Zero is invalid price.
RequestValidationError.BuySellMismatchBuy/Sell side of the accepted price is incorrect.
RequestValidationError.InvalidQuoteIDThe rateId of the previously quoted (PQ) order is invalid.
RequestValidationError.LegalEntitySetIncorrectlyAccount field incorrect.
RequestValidationError.OrderTypeNotSupportedOrder type not supported.
RequestValidationError.PriceMismatchAccepted price not the same as previously quoted price.
RequestValidationError.QuoteExpiredRate associated with the rateId not found. It has expired. Price is no longer valid.
RequestValidationError.tradingDisabledTrading is disabled.
Overview
License Integral
Languages
Servers
Mock server
https://docs.fxinside.net/_mock/openapi/integral-api-reference/rest/
https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com/

Authentication API

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:

  1. Send your request:
    • Set the symbol, tenor, amount, and buy/sell direction.
    • Set the rfq parameter to false.
    • Set the expiry parameter to the expiration time of your stream request.
  2. Query the state of your request.
  3. Do one of the following:
    • Accept the quote.
    • Withdraw your quote request.
    • Let your quote request expire.

Request for Quote (RFQ) workflow:

  1. Send your request:
    • Set the symbol, tenor, amount, and buy/sell direction.
    • Set the rfq parameter to true.
    • Set the expiry parameter to your requested duration of the quote.
  2. Query the state of your request.
  3. Do one of the following:
    • Accept the quote.
    • Withdraw your quote request.
    • Let your quote request expire.
Operations

Positions

Get open positions.

Operations

Custody

Custody operations.

Operations

STP download

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.

Operations

Get done trades

Request

Get executed trades that have not been downloaded before. The default maximum number of trades returned is determined by the server. You should poll this endpoint until you receive an empty response indicating that there are no remaining executed trades available for STP download.

To get trades that have been previously downloaded, you must first call the Prepare trades to resend endpoint.

Query
maxCountinteger

Max number of trades to download. If not specified, the default max number of trades is used (currently 50).

Default 50
Example: maxCount=20
No request payload

Responses

A list of executed trades. An empty response indicates no executed trades available.

Bodyapplication/jsonArray [
orderIdstring<= 60 charactersrequired

Order ID. For cover trades, this is the cover order ID.

tradeIdstring<= 255 charactersrequired

Integral trade ID.

coIdstring<= 255 charactersrequired

Customer-supplied order ID.

eventstring<= 50 charactersrequired

Status of the trade so you can decide how to treat the download.

  • NEW: Trade downloaded for the first time.
  • RESEND: A previously downloaded trade that is sent again with no changes
tradeTypestring<= 20 charactersrequired

Trade type:

  • Spot
  • Outright
  • NDF
  • Swap
  • FwdFwd
  • NDFSwap
tradeDatestring<= 20 charactersrequired

Date the trade was initiated in the format YYYY-MM-DD.

valueDatestring<= 20 charactersrequired

Value date in the format YYYY-MM-DD.

fixingDatestring<= 20 characters

(NDF trades) Fixing date in the format YYYY-MM-DD.

fixingTenorstring<= 20 characters

(NDF trades) Fixing tenor.

makerbooleanrequired
  • true: Maker (the deal was initiated by submitting a request or from working the balance on an outstanding order).
  • false: Taker (the deal was initiated by taking a dealable price in the app).
sidestring<= 10 charactersrequired

Side of the order from the customer's perspective, either Buy or Sell.

statusstring<= 20 charactersrequired

Status of the trade when the message was created. STP returns only Verified trades.

symbolstring<= 35 charactersrequired

Dealt instrument pair (currency, metal, energy, index, crypto), for example AUD/USD.

currencystring<= 10 charactersrequired

Dealt currency, for example AUD.

rateIdstring<= 255 characters

May be omitted. ID of the originating rate for previously quoted (PQ) orders.

customerAccountstring<= 30 characters

Settlement code when available.

customerOrgstring<= 30 charactersrequired

Customer org ID.

userstring<= 100 charactersrequired

Full name of the user who entered the trade.

counterpartystring<= 30 charactersrequired

Counterparty ID.

counterpartyLongNamestring<= 255 characters

Counterparty name.

counterpartyTradeIdstring or null<= 255 characters

Trade ID assigned by counterparty.

counterpartyAccountstring<= 30 characters

Counterparty settlement code when available.

channelstring<= 100 characters

Workflow, app, and UI component that originated the request.

channelCategorystring<= 50 characters

Category of trade origin or intent. Applicable when received by a taker.

  • GUI
  • API
  • COVER
  • HEDGE_RISK
tenorstring<= 50 characters

May be omitted. Trade tenor.

  • Today: today
  • TOD: today
  • ON: overnight (today)
  • TN: tomorrow
  • SP: spot
  • SPOT: spot
  • SN: spot next (spot+1)
  • nD: a number of days after the current business date (for example, 1D, 2D, 10D)
  • nW: a number of weeks after the current business date (for example, 1W, 2W, 3W)
  • nM: a number of months after the current business date (for example, 1M, 2M, 3M)
  • nY: a number of years after the current business date (for example, 1Y, 2Y, 3Y)
  • nIMM: The next International Monetary Market (IMM) settlement date. IMM dates are the third Wednesday of the last month of every quarter (March, June, September, December). IMM results in the next IMM date on or after the spot date. 2IMM results in two IMM dates after the spot date.
  • SnIMM: (spot + IMM) for swaps
  • TnIMM: (tomorrow + IMM) for swaps
farTenorstring<= 50 characters

May be omitted. Far-leg tenor for swaps.

  • Today: today
  • TOD: today
  • ON: overnight (today)
  • TN: tomorrow
  • SP: spot
  • SPOT: spot
  • SN: spot next (spot+1)
  • nD: a number of days after the current business date (for example, 1D, 2D, 10D)
  • nW: a number of weeks after the current business date (for example, 1W, 2W, 3W)
  • nM: a number of months after the current business date (for example, 1M, 2M, 3M)
  • nY: a number of years after the current business date (for example, 1Y, 2Y, 3Y)
  • nIMM: The next International Monetary Market (IMM) settlement date. IMM dates are the third Wednesday of the last month of every quarter (March, June, September, December). IMM results in the next IMM date on or after the spot date. 2IMM results in two IMM dates after the spot date.
  • SnIMM: (spot + IMM) for swaps
  • TnIMM: (tomorrow + IMM) for swaps
farFixingTenorstring<= 50 characters

May be omitted. Far-leg fixing tenor for NDF swaps. Required if farFixingDate not specified.

  • Today: today
  • TOD: today
  • ON: overnight (today)
  • TN: tomorrow
  • SP: spot
  • SPOT: spot
  • SN: spot next (spot+1)
  • nD: a number of days after the current business date (for example, 1D, 2D, 10D)
  • nW: a number of weeks after the current business date (for example, 1W, 2W, 3W)
  • nM: a number of months after the current business date (for example, 1M, 2M, 3M)
  • nY: a number of years after the current business date (for example, 1Y, 2Y, 3Y)
  • nIMM: The next International Monetary Market (IMM) settlement date. IMM dates are the third Wednesday of the last month of every quarter (March, June, September, December). IMM results in the next IMM date on or after the spot date. 2IMM results in two IMM dates after the spot date.
  • SnIMM: (spot + IMM) for swaps
  • TnIMM: (tomorrow + IMM) for swaps
farFixingDatestring<= 20 characters

May be omitted. Far-leg fixing date for NDF swaps in the format YYYY-MM-DD. Required if farFixingTenor not specified.

farValueDatestring<= 20 characters

May be omitted. Far-leg value date for swaps in the format YYYY-MM-DD.

farSidestring<= 10 characters

May be omitted. Side of the far leg for swaps.

customerLEIstring<= 100 characters

May be omitted. Customer LEI code.

counterpartyLEIstring<= 100 characters

May be omitted. Counterparty LEI code.

upistring<= 50 characters

May be omitted. Unique Product Identifier for SEF trades.

utistring<= 150 characters

May be omitted. Unique Transaction Identifier for SEF trades.

usistring<= 150 characters

May be omitted. Unique Swap Identifier for near leg of SEF swaps.

farUSIstring<= 150 characters

May be omitted. Unique Swap Identifier for far leg of SEF swaps.

exchangestring<= 30 characters

May be omitted. Exchange ID.

portfolioIdstring<= 100 characters

May be omitted. For batch trades and SSPs, the containing portfolio ID.

parentUSIstring<= 150 characters

May be omitted. Unique Swap Identifier for SEF swaps.

isNetboolean

Whether or not the trade was done to net another trade.

midMarketboolean

Whether or not the trade was done at the mid-market rate.

regulatoryobject

May be omitted. An object containing regulatory information.

benchmarkRatenumber(double)

Reference benchmark rate.

farLegISINstring<= 12 characters

May be omitted. Far-leg International Securities Identification Number for multi-leg trades.

nearLegISINstring<= 12 characters

May be omitted. Near-leg International Securities Identification Number for multi-leg trades.

isinLinkIdstring<= 12 characters

May be omitted. International Securities Identification Number link ID.

notesstring<= 255 characters

May be omitted. Any notes on the order entered by the order submitting user.

executionTimestring<= 32 charactersrequired

Date and time trade was done in the format yyyy-MM-dd HH:mm:ss,SSS Z.

dealtAmountnumber(double)required

Amount of the dealt currency.

settledAmountnumber(double)

Amount of the settlement currency.

baseAmountnumber(double)required

Amount of base currency.

termAmountnumber(double)required

Amount of term currency.

spotRatenumber(double)required

Spot rate of the trade or near leg of the trade.

ratenumber(double)required

All-in rate.

forwardPointsnumber(double)

May be omitted. Forward points for outright trades and near leg of swaps.

swapPointsnumber(double)

May be omitted. Swap points, if any.

farRatenumber(double)

May be omitted. Far-leg rate for swaps.

farDealtAmountnumber(double)

May be omitted. Far-leg amount in the dealt instrument for swaps.

farSettledAmountnumber(double)

May be omitted. Far-leg amount in the settlement instrument for swaps.

farBaseAmountnumber(double)

May be omitted. Far-leg amount in the base instrument for swap.

farTermAmountnumber(double)

May be omitted. Far-leg amount in the term instrument for swaps.

farForwardPointsnumber(double)

May be omitted. Far-leg forward points for swaps.

mifidBenchmarkRatenumber(double)

May be omitted. Reference benchmark rate per MiFID II.

feesnumber(double)

May be omitted. Fees on the trade, if any.

initialSettledAmountnumber(double)

May be omitted. Initial settled amount before any amendment.

streamstring<= 30 characters

May be omitted. ID of the stream that priced the trade.

midRatenumber(double)

May be omitted. Spot or near-leg mid rate for swaps.

farMidRatenumber(double)

May be omitted. Far-leg mid rate for swaps.

coverRatenumber(double)

May be omitted. Rate of the trade that covered this trade.

coverSpotRatenumber(double)

May be omitted. Spot rate of the trade that covered this trade.

coverForwardPointsnumber(double)

May be omitted. Forward points of the trade that covered this trade.

coverFarRatenumber(double)

May be omitted. Far-leg rate of the trade that covered this trade.

coverFarSpotRatenumber(double)

May be omitted. Far-leg spot rate of the trade that covered this trade.

coverFarForwardPointsnumber(double)

May be omitted. Far-leg forward points of the trade that covered this trade.

coverRiskManagementTypestring<= 20 characters

Cover risk management type. Applicable when received by a maker.

  • COVER
  • NO_COVER
  • WAREHOUSE
spreadsobject

May be omitted. Spreads on the trade. Available to makers who have configured STP to include market rate and spreads.

bookNamestring<= 30 characters

May be omitted. Only applicable to FX Yield Manager. If FX Yield Manager is used to manage positions, this is the name of the book, if any, to which the trade is entered.

  • A = Cover trades, both customer trades and its cover trades.
  • B = Warehoused customer trades, FX Yield Manager hedging trades.
  • empty = No-cover trades, unmanaged trades, desk trades.
coveredTradeIdstring<= 255 characters

May be omitted. ID of the trade covered by this trade, if any.

coveredCounterpartystring<= 30 characters

ID of the customer org that originated the trade with the broker.

isSyntheticboolean

May be omitted. Whether or not the symbol is a synthetic currency pair.

syntheticComponentstring<= 10 characters

May be omitted. Component currency used to price the synthetic currency pair.

MT300Field72string<= 210 characters

SWIFT MT 300 Foreign Exchange Confirmation, field 72 Sender to Receiver Information

]
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"
  }
]

Prepare trades to resend

Request

Set previously downloaded trades with tradeDate within the specified date range as eligible for download. You must then call the Get trades endpoint to download the trades. The event attribute on previously downloaded trades is always set to RESEND.

Bodyapplication/json
startDatestring<= 32 charactersrequired

Beginning tradeDate of trades to reset for STP eligibility, inclusive, in the format yyyy-MM-dd HH:mm:ss,SSS Z.

Example: "2022-04-21 13:00:00,000 +0000"
endDatestring<= 32 charactersrequired

End tradeDate of trades to reset for STP eligibility, inclusive, in the format yyyy-MM-dd HH:mm:ss,SSS Z.

Example: "2022-04-22 13:00:00,000 +0000"
application/json
{
  "startDate": "2022-04-21 13:00:00,000 +0000",
  "endDate": "2022-04-22 13:00:00,000 +0000"
}

Responses

Successful request. You must call the Get trades endpoint to download the trades.

Reference data

Fundamental business data (such as accounts, assets, and symbols) used by multiple endpoints.

Operations