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
HMAC authentication

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
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

Signature parameters

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.

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.

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.
`RequestValidationError.tradingDisabled`	Trading is disabled.

Overview

License Integral

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

Get spot rate by symbol

Request

Get real-time, top-of-book spot bid and offer rates for a given symbol. Returns an aggregated list of rates, which may include prices from multiple liquidity providers or external market data sources.

Query

symbolstring<= 35 charactersrequired

Base and term currency separated by a slash /.

Example: symbol=EUR/USD

No request payload

Responses

A spot rate object with top-of-book spot rates.

Bodyapplication/json

symbolstring<= 35 characters

bidnumber(double)

offernumber(double)

bidLimitnumber(double)

offerLimitnumber(double)

timeinteger(int64)

rateIdstring<= 255 characters

Response

application/json

{
  "symbol": "EUR/USD",
  "bid": 1.1863,
  "offer": 1.18638,
  "bidLimit": 1000000,
  "offerLimit": 1000000,
  "time": 1602536120080,
  "rateId": "2022-11-10-EURUSD-SPOT-435ef73249"
}

Get spot rate by type and symbol

Request

Get real-time spot bid and offer rates by rate type and symbol. Returns an aggregated list of rates, which may include prices from multiple liquidity providers or external market data sources.

Path

typestring<= 32 charactersrequired

The type of rates requested: TOB=top of book, FULL=full book, RAW=raw rates

Default "TOB"

Query

symbolstring<= 35 charactersrequired

Base and term currency separated by a slash /.

Example: symbol=EUR/USD

No request payload

Responses

A spot rate object with one or more spot rates depending on the request.

Bodyapplication/json

One of:

symbolstring<= 35 characters

bidnumber(double)

offernumber(double)

bidLimitnumber(double)

offerLimitnumber(double)

timeinteger(int64)

rateIdstring<= 255 characters

Response

application/json

type=TOB (spot rate object with top-of-book rates)

{
  "symbol": "EUR/USD",
  "bid": 1.1863,
  "offer": 1.18638,
  "bidLimit": 1000000,
  "offerLimit": 1000000,
  "time": 1602536120080,
  "rateId": "2022-11-10-EURUSD-SPOT-435ef73249"
}

Get spot rate by type and symbol for organization

Request

Get real-time spot bid and offer rates by rate type and symbol from liquidity providers for an organization. Returns an aggregated list of rates, which may include prices from multiple liquidity providers or external market data sources.

Path

typestring<= 32 charactersrequired

The type of rates requested: TOB=top of book, FULL=full book, RAW=raw rates

Example: TOB

orgstring<= 30 charactersrequired

Organization ID of requesting user. Rates returned are from liquidity providers configured for the organization.

Example: BrokerOrgA1

Query

symbolstring<= 35 charactersrequired

Base and term currency separated by a slash /.

Example: symbol=EUR/USD

No request payload

Responses

A spot rate object with one or more spot rates depending on the request.

Bodyapplication/json

One of:

symbolstring<= 35 characters

bidnumber(double)

offernumber(double)

bidLimitnumber(double)

offerLimitnumber(double)

timeinteger(int64)

rateIdstring<= 255 characters

Response

application/json

type=TOB (spot rate object with top-of-book rates)

{
  "symbol": "EUR/USD",
  "bid": 1.1863,
  "offer": 1.18638,
  "bidLimit": 1000000,
  "offerLimit": 1000000,
  "time": 1602536120080,
  "rateId": "2022-11-10-EURUSD-SPOT-435ef73249"
}

Get market data

Request

Get rates from market data sets (MDSs) managed by the Integral Pricing engine.

The MDS workflow determines the parameters you need to send and the type of rates you receive.

Regular workflow
End-of-day workflow
Fixed-period workflow

Regular workflow

A regular MDS contains active market rates.

Required parameter values for regular rates:

id: you must include the ID of a regular MDS.
org: you must omit this parameter for regular rates. If you specify the id of a regular MDS and the org parameter, an error is returned.
symbol: you must include either symbol or symbols. If neither is included, an error is returned.
symbols: you must include either symbol or symbols. If neither is included, an error is returned.

Example: regular rates for a single currency pair, SPOT, for today's business date

/marketdataset?id=RealTimeMDS&symbol=EUR/USD

Example: regular rates for multiple currency pairs, 1-week outright, for today's business date

/marketdataset?id=RealTimeMDS&symbols=EUR/USD,USD/JPY,USD/CAD&tenor=1W

End-of-day workflow

An end-of-day MDS contains reference rates and is active after a specific time, typically after the end of the business day.

Required parameter values for end-of-day rates:

id: you must include the ID of an end-of-day MDS.
org: you must omit this parameter for end-of-day rates. If you specify the id of a end-of-day MDS and the org parameter, an error is returned.
symbol: you must include either symbol or symbols. If neither is included, an error is returned.
symbols: you must include either symbol or symbols. If neither is included, an error is returned.

Example: end-of-date rates for a single currency pair, SPOT, for today's business date

/marketdataset?id=EODMDS&symbol=EUR/USD

Example: end-of-date rates for a single currency pair, SPOT, for a specific date

/marketdataset?id=EODMDS&symbol=EUR/USD&date=2024-10-24

Fixed-period workflow

A fixed-period MDS contains rates generated at a specific time and that are active and valid during a specified time window with a start and end time.

Required parameter values for fixed-period rates:

id: you must include either id or org. Do not include both. Specify the MDS ID for fixed-period rates from a specific fixed-period MDS.
org: you must include either id or org. Do not include both. Specify the organization ID for rates from all fixed-period MDSs for the organization.

Example: fixed-period rates for a single currency pair, SPOT, for today's business date

/marketdataset?id=FixedPeriodMDS&symbol=EUR/USD

Example: fixed-period rates for a single currency pair, SPOT, for a specific date, active during a specific time window

/marketdataset?id=FixedPeriodMDS&symbol=EUR/USD&date=2024-10-24&timeWindow=1500-1700

Example: all fixed-period MDSs for an organization, SPOT, for a specific date, active during a specific time window

/marketdataset?org=organizationID&date=2024-10-24&timeWindow=1500-1700

Query

idstring<= 30 charactersrequired

ID of market data set from the Integral Pricing Engine.

Required for regular market data sets.

Optional for EOD and fixed-period market data sets.

If not included, you must include org. Do not include both id and org in your request.

Examples:

You must include an ID for regular market data. id=RealTimeMDS

Include an EOD market-data set ID for exclusively EOD market data. You may omit the ID to receive EOD and fixed-period market data. id=EODMDS

Include a fixed-period market-data set ID for exclusively fixed-period market data. You may omit the ID to receive EOD and fixed-period market data. id=FixedPeriodMDS

orgstring<= 30 charactersrequired

ID of the organization that the market-data-set pricing stream is assigned to by the Integral Pricing Engine.

Omit for regular market data sets.

If not included, you must include id.

Do not include both id and org in your request.

Example: org=BNK1-4HOrg

symbolstring<= 35 charactersrequired

Base and term currency separated by a slash "/". Optional for fixed-period workflow. For regular and end-of-day workflows, you must include either symbol or symbols. If neither is included, an error is returned.

Example: symbol=EUR/USD

symbolsstring<= 255 charactersrequired

Comma-separated list of currency pairs. Each currency pair consists of base and term currencies separated by a slash "/" (for example EUR/USD,USD/JPY,NZD/USD). Optional for fixed-period workflow. For regular and end-of-day workflows, you must include either symbol or symbols. If neither is included, an error is returned.

Example: symbols=EUR/USD,USD/JPY

datestring<= 20 characters

Business date for the market data set in the format YYYY-MM-DD.

If not specified, the current business date is used.

Applicable only to end-of-day and fixed-period MDSs. Ignored for regular MDSs.

Default "Current business date"

Example: date=2024-10-24

tenorstring<= 20 characters

MDS tenor. If not specified, all rates configured in the MDS are returned.

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

Default "SPOT"

timeWindowstring<= 53 characters

Time in 24-hour format during which the market date set is active, either a discrete time hhmm or a time period with a start time and end time hhmm-hhmm. If not specified, currently active market data sets are returned.

Default "Currently active market data sets"

Example: timeWindow=1500-1700

No request payload

Responses

A market data set object containing one or more rates.

Bodyapplication/jsonArray [

idstring<= 30 characters

ID of market data set as defined in the Integral Pricing Engine.

datestring or null<= 20 characters

Business date of the current market data set in the format YYYY-MM-DD. Applicable to end-of-day and fixed-period MDSs only. Null for regular MDSs.

timeWindowstring or null<= 53 characters

Applicable to fixed-period market data sets only. Time window when the rates in the market data set are active. Specified in 24-hour format from start time to end time (hhmm-hhmm).

namestring<= 50 characters

Descriptive name of market data set.

createdTimestring or null<= 32 characters

Market data set creation date/time in the 24-hour format yyyy-MM-dd HH:mm:ss,SSS Z.

activationTimestring or null<= 32 characters

Applicable to fixed-period market data sets only. Market data set activation date/time in the 24-hour format yyyy-MM-dd HH:mm:ss,SSS Z.

validUntilstring or null<= 32 characters

Applicable to fixed-period market data sets only. Date/time the market data set is valid until in the 24-hour format yyyy-MM-dd HH:mm:ss,SSS Z.

nextCreationTimestring or null<= 32 characters

Applicable to fixed-period market data sets only. Date/time in 24-hour GMT the next market data set creation in the format yyyy-MM-dd HH:mm:ss,SSS Z.

expirationTimestring or null<= 32 characters

Applicable to fixed-period market data sets only. Date/time at which the market data set expires in the format yyyy-MM-dd HH:mm:ss,SSS Z. The time is calculated by adding the Create Frequency value from the MDS configuration in the pricing engine to the activationTime value.

ratesArray of objects

Collection of rates.

]

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": [ … ]
  }
]

Get benchmark

Request

Get the Integral FX benchmark rate for a given symbol.

Query

symbolstring<= 35 charactersrequired

Base and term currency separated by a slash /.

Example: symbol=AUD/USD

No request payload

Responses

An object with the Integral FX benchmark rate.

Bodyapplication/json

symbolstring<= 35 characters

Base and term currency separated by a slash / (for example EUR/USD).

Example: "AUD/USD"

ratenumber(double)

Benchmark rate.

Example: 0.69746

uidstring<= 128 characters

GUID for the rate.

Example: "G-4796976cd-17528d7b6ea-FXB-6237f19"

timestampinteger(int64)

Rate timestamp in milliseconds Unix time, UTC timezone.

Example: 1602708027114

Response

application/json

{
  "symbol": "AUD/USD",
  "rate": 0.69746,
  "uid": "G-4796976cd-17528d7b6ea-FXB-6237f19",
  "timestamp": 1602708027114
}

Get ticker

Request

Get the last traded price for a given symbol.

Query

symbolstring<= 35 charactersrequired

Base and term currency separated by a slash /.

Example: symbol=EUR/USD

No request payload

Responses

An object with the last traded price.

Bodyapplication/json

symbolstring<= 35 characters

Base and term currency separated by a slash / (for example EUR/USD).

Example: "AUD/USD"

ratenumber(double)

Rate, either bid or offer based on value of bid attribute.

Example: 0.69746

isBidstring<= 6 characters

Whether or not the rate is bid or offer:

true=bid
false=offer

Example: true

timestampinteger(int64)

Rate timestamp in Unix time, UTC timezone.

Example: 1602505075906

bidboolean

Whether or not the rate is bid or offer:

true=bid
false=offer

Example: true

Response

application/json

{
  "symbol": "AUD/USD",
  "rate": 0.69746,
  "isBid": true,
  "timestamp": 1602505075906,
  "bid": true
}

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.
- Set the rfq parameter to false.
- Set the expiry parameter to the expiration time of your stream request.
Query the state of your request.
Do one of the following:
- Accept the quote.
- Withdraw your quote request.
- Let your quote request expire.

Request for Quote (RFQ) workflow:

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.
Query the state of your request.
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

Reference data

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

Operations

REST API (1.0.1)

Authentication options

Token-based authentication

Get token

Pass token

Renew token

HMAC authentication

Signature parameters

Sample authorization header

Signature string construction

API tracing

Status and error codes

Reason codes

Authentication API

Market data

Get spot rate by symbol

Request

Responses

Was this helpful?

Get spot rate by type and symbol

Request

Responses

Was this helpful?

Get spot rate by type and symbol for organization

Request

Responses

Was this helpful?

Get market data

Request

Regular workflow

Example: regular rates for a single currency pair, SPOT, for today's business date

Example: regular rates for multiple currency pairs, 1-week outright, for today's business date

End-of-day workflow

Example: end-of-date rates for a single currency pair, SPOT, for today's business date

Example: end-of-date rates for a single currency pair, SPOT, for a specific date

Fixed-period workflow

Example: fixed-period rates for a single currency pair, SPOT, for today's business date

Example: fixed-period rates for a single currency pair, SPOT, for a specific date, active during a specific time window

Example: all fixed-period MDSs for an organization, SPOT, for a specific date, active during a specific time window

Responses

Was this helpful?

Get benchmark

Request

Responses

Was this helpful?

Get ticker

Request

Responses

Was this helpful?

Orders

Trades

RFS/RFQ

Positions

Custody

STP download

Reference data