API reference
/
REST API
/
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

Book trade

Request

Enter trades done in other systems.

Bodyapplication/json
typestring<= 20 charactersrequired

Trade type: Spot, Outright, Swap, NDF

channelstring<= 10 charactersrequired

The workflow that originated the request. For reference in monitoring and reports. Values provided by Integral as applicable.

  • 0 = API/CreditEntry.
  • 1 = API/TradeEntry.
clientRequestIdstring<= 255 characters

ID of the book trade request assigned by you. Returned in the success response so that you can associate the request and booked trade.

referenceIdstring<= 255 characters

Free text for additional information and the ID, if any, assigned to the trade by the trade entry organization for their reference.

notestring<= 255 characters

Any notes on the trade. These notes are sent via STP if the trade is eligible for STP (stp=true).

counterpartyAccountstring<= 30 charactersrequired

Maker account ID (legal entity).

counterpartystring<= 30 charactersrequired

Counterparty organization ID.

counterpartyTraderstring<= 30 characters

Counterparty user ID. If not specified, the organization's default user as configured in the Integral system is used.

customerAccountstring<= 30 charactersrequired

Customer legal entity ID.

customerOrgstring<= 30 charactersrequired

Customer organization ID.

traderstring<= 30 characters

Customer user ID. If not specified, the default user of the customer organization is used.

dealtInsstring<= 17 charactersrequired

The dealt instrument, typically three-character ISO code (for example, AUD).

dealtAmountnumber(double)required

Amount of the dealt instrument for the trade or near leg of swaps.

baseAmountnumber(double)

Amount of base instrument.

termAmountnumber(double)

Amount of term instrument.

ratenumber(double)required

All-in rate to the precision of the currency pair’s quote convention. Trades with rates that are higher precision than allowed are rejected.

sidestring<= 4 charactersrequired

The side of the order from the customerOrg perspective, either BUY or SELL.

symbolstring<= 35 charactersrequired

The dealt instrument pair (currency, metal, energy, index, crypto), seven-character ISO code (for example, AUD/USD).

tradeDatestring<= 20 charactersrequired

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

tenorstring<= 20 characters

Trade tenor. You must specify either valueDate or tenor. If you specify both, tenor is ignored.

  • 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
valueDatestring<= 20 charactersrequired

Value date for the trade or near leg of swaps in the format YYYY-MM-DD. You must specify either valueDate or tenor. If you specify both, tenor is ignored.

fixingDatestring<= 20 characters

Fixing date for NDFs in the format YYYY-MM-DD. Required if fixingTenor not specified.

fixingTenorstring<= 20 characters

Fixing tenor for NDFs in the format YYYY-MM-DD. Required if fixingDate not specified.

spotRatenumber(double)

Spot rate of the trade or near leg of the trade. Required for outrights, swaps, and NDFs.

forwardPointsnumber(double)

Required for outrights, near leg of forward/forward swaps, and NDFs. Forward points for outrights and near leg of forward/forward swaps.

Default 0
coverRatenumber(double)

All-in rate at which the trade or near leg was hedged by the trader in the market.

farSidestring<= 4 characters

Required for swaps. BUY or SELL (case sensitive), the side of the far-leg dealt currency from the customerOrg perspective.

farDealtAmountnumber(double)

Required for swaps. Far-leg amount of the dealt instrument.

farForwardPointsnumber(double)

Required for swaps. Far-leg forward points.

Default 0
farRatenumber(double)

Required for swaps. Far-leg all-in rate.

farTenorstring<= 20 characters

Required for swaps. Far-leg tenor. Must be later than the near-leg value date in valueDate or tenor. You must specify either farValueDate or farTenor. If you specify both, farTenor is ignored.

farValueDatestring<= 20 characters

Required for swaps. Value date for the far leg of swaps in the format YYYY-MM-DD. Must be later than the near-leg value date in valueDate or tenor. You must specify either farValueDate or farTenor. If you specify both, farTenor is ignored.

farCoverRatenumber(double)

All-in rate at which the far leg was hedged by the trader in the market.

farFixingDatestring<= 20 characters

NDF far-leg fixing date in the format YYYY-MM-DD. Required if farFixingTenor not specified.

farFixingTenorstring<= 20 characters

NDF far-leg fixing tenor. Required if farFixingDate not specified.

bookNamestring<= 10 characters

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.
creditModeinteger(int32)

How the trade is considered for credit by Integral:

  • 0 = CreditCheck: Trade request is rejected if credit is not available.
  • 1 = CreditOvershoot: Trade request is accepted even if credit is not available. Credit can overshoot the available limit.
  • 2 = CreditIgnore: Credit is not taken.
Default 0
creditValuationAdjustmentnumber(double)

Credit valuation factor of customerOrg provided by counterparty.

rateIdstring<= 255 characters

ID of the originating rate, if any.

stpboolean

If true or not included on the message, STP download is determined by the trade entry organization’s STP configuration. False overrides the organization’s settings and the trade is not sent via STP.

application/json
{
  "type": "Spot",
  "channel": "1",
  "clientRequestId": "req Spot 644",
  "counterparty": "BrokerOrg",
  "counterpartyAccount": "BrokerOrgLE",
  "counterpartyTrader": "BrokerOrgUser",
  "coverRate": 1.1234,
  "creditMode": 2,
  "creditValuationAdjustment": 1.44,
  "customerAccount": "CustOrg1le1",
  "customerOrg": "CustOrg1",
  "trader": "CustOrg1User",
  "dealtAmount": 2000000,
  "dealtIns": "USD",
  "note": "Notes on trade",
  "rate": 1.09706,
  "rateId": "2022-05-12-GBPUSD-SP-435cd558",
  "referenceId": "ref A4f2",
  "side": "SELL",
  "spotRate": 1.09696,
  "stp": true,
  "symbol": "GBP/USD",
  "tradeDate": "2022-05-12",
  "valueDate": "2022-05-17"
}

Responses

The ID and creation time of the book trade in Integral’s system.

Bodyapplication/json
tradeIdstring<= 255 characters

The ID of the booked trade in Integral’s system.

Example: "FXI30501001"
createdTimestring<= 32 characters

The date and time (GMT) the trade was booked in the format yyyy-MM-dd HH:mm:ss,SSS Z.

Example: "2022-01-19 12:36:27,200 +0000"
clientRequestIdstring<= 255 characters

ID book trade request assigned by you. Returned so that you can associate the request and booked trade.

Example: "req swap 1"
Response
application/json
{
  "tradeId": "FXI30501001",
  "createdTime": "2022-01-19 12:36:27,200 +0000",
  "clientRequestId": "req swap 1"
}

Query all trades on an order by ID

Request

Get all fills for the order ID assigned by Integral returned in the coId or orderId field when the order was placed.

Query
coIdstring<= 255 charactersrequired

The unique ID assigned by you when your order was placed. Returned in response in the coId field.

Example: coId=OrderXEL278vv1
orderIdstring<= 255 charactersrequired

The unique ID assigned by Integral when your order was placed. Returned in response in the orderId field.

Example: orderId=4820275011
No request payload

Responses

An array of trade objects. If an empty array, no trades were done for the given server order ID.

Bodyapplication/jsonArray [
orderIdstring<= 60 characters

Order ID.

tradeIdstring<= 255 characters

Integral trade ID.

tradeTypestring<= 20 characters

Trade type:

  • Spot
  • Outright
  • Swap
  • FwdFwd
  • NDF
  • NDFSwap
tenorstring<= 20 characters

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
tradeDatestring<= 20 characters

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

valueDatestring<= 20 characters

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.

executionTimestring<= 32 characters

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

makerboolean
  • 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).
orderSidestring<= 10 characters

Side of the order from your perspective, either Buy or Sell.

statusstring<= 32 characters

Status of the trade when the message was created:

  • Pending
  • Verified
  • Rejected
rejectReasonstring<= 128 characters

The reason for trade rejection, if any.

symbolstring<= 35 characters

Dealt instrument pair (currency, metal, energy, index, crypto), seven-character ISO code (for example, AUD/USD).

dealtInsstring<= 17 characters

Dealt instrument, three-character ISO code (for example, AUD).

dealtAmountnumber(double)

Amount of the dealt instrument or near-leg instrument.

settledAmountnumber(double)

Amount of the settlement instrument.

baseAmountnumber(double)

Amount of base instrument.

termAmountnumber(double)

Amount of term instrument.

spotRatenumber(double)

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

ratenumber(double)

All-in rate.

orderTypestring<= 20 characters

Type of order.

rateIdstring<= 255 characters

ID of the originating rate, if any.

forwardPointsnumber(double)

Forward points for outright trades and near leg of swaps.

swapPointsnumber(double)

Swap points, if any.

customerAccountstring<= 30 characters

Customer legal entity ID.

customerOrgstring<= 30 characters

Customer org ID.

traderstring<= 30 characters

Customer trader user who did the trade.

counterpartystring<= 30 characters

Counterparty ID.

cptyLongNamestring<= 128 characters

Counterparty name.

coverTradeIdsArray of strings

List of ID for trades that cover this trade, if any.

cptyTradeIdstring or null<= 255 characters

Trade ID assigned by counterparty.

counterpartyAccountstring<= 30 characters

Counterparty legal entity ID.

channelstring<= 100 characters

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

farTenorstring<= 20 characters

Far-leg tenor for swaps.

farFixingTenorstring<= 20 characters

Far-leg fixing tenor for NDF swaps.

farFixingDatestring<= 20 characters

Far-leg fixing date for NDF swaps in the format YYYY-MM-DD.

farValueDatestring<= 20 characters

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

farSidestring<= 10 characters

Side of the far leg for swaps.

farRatenumber(double)

Far-leg rate for swaps.

farDealtAmountnumber(double)

Far-leg amount in the dealt instrument for swaps.

farSettledAmountnumber(double)

Far-leg amount in the settlement instrument for swaps.

farBaseAmountnumber(double)

Far-leg amount in the base instrument for swap.

farTermAmountnumber(double)

Far-leg amount in the term instrument for swaps.

farForwardPointsnumber(double)

Far-leg forward points for swaps.

counterpartyALEIstring<= 100 characters

LEI code for counterpartyA.

counterpartyBLEIstring<= 100 characters

LEI code for counterpartyB.

externalRequestIdstring<= 255 characters

The ID of the originating request for price from a system external to Integral.

requestIdstring<= 255 characters

The ID of the originating request for price from Integral systems.

portfolioIdstring<= 100 characters

Containing portfolio ID for batch trades and SSPs.

benchmarkRatenumber(double)

Reference benchmark rate.

outrightobject

Forward pricing info for the trade.

farLegISINstring<= 12 characters

Far-leg International Securities Identification Number for multi-leg trades.

nearLegISINstring<= 12 characters

Near-leg International Securities Identification Number for multi-leg trades.

regulatoryobject

An object containing regulatory information.

feesnumber(double)

Fees on the trade, if any.

initialSettledAmountnumber(double)

The initial settled amount before any amendment.

notesstring<= 255 characters

Any notes on the order entered by the order submitting user.

midMarketboolean

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

utistring<= 150 characters

The Unique Trade Identifier if the trade was done in a SEF.

upistring<= 50 characters

The Unique Product Identifier if the trade was done in a SEF.

isinLinkIdstring<= 12 characters

International Securities Identification Number link ID.

]
Response
application/json
[
  {
    "orderId": "4821376492",
    "tradeId": "FXI9222972502",
    "tradeType": "Spot",
    "tenor": "SPOT",
    "tradeDate": "2022-08-16",
    "valueDate": "2022-08-18",
    "executionTime": "2022-08-16 08:24:13,239 +0000",
    "maker": false,
    "orderSide": "Sell",
    "status": "Verified",
    "symbol": "EUR/USD",
    "dealtIns": "EUR",
    "customerAccount": "Cust12LE",
    "customerOrg": "Cust12",
    "trader": "MD",
    "counterparty": "SOR4",
    "cptyLongName": "SOR4",
    "coverTradeIds": [],
    "cptyTradeId": "Exec-db08b0657900eb",
    "counterpartyAccount": "SOR4LE",
    "counterpartyALEI": "549300YLYOXGEYO4YK89",
    "externalRequestId": "FXI9222877130",
    "benchmarkRate": 0,
    "dealtAmount": 2000000,
    "settledAmount": 2372460,
    "baseAmount": 2000000,
    "termAmount": 2372460,
    "spotRate": 1.18623,
    "rate": 1.18623,
    "fees": 0,
    "initialSettledAmount": 2372460,
    "midMarket": false,
    "upi": "EUR_USD_SPOT",
    "uti": "MCQRZU5ST1INP9222972502"
  },
  {
    "orderId": "4821376492",
    "tradeId": "FXI9222972501",
    "tradeType": "Spot",
    "tenor": "SPOT",
    "tradeDate": "2022-08-16",
    "valueDate": "2022-08-18",
    "executionTime": "2022-08-16 08:24:15,882 +0000",
    "maker": false,
    "orderSide": "Sell",
    "status": "Verified",
    "symbol": "EUR/USD",
    "dealtIns": "EUR",
    "customerAccount": "Cust12LE",
    "customerOrg": "Cust12",
    "trader": "MD",
    "counterparty": "SOR4",
    "cptyLongName": "SOR4",
    "coverTradeIds": [],
    "cptyTradeId": "Exec-db08b064811338",
    "counterpartyAccount": "SOR4LE",
    "counterpartyALEI": "549300YLYOXGEYO4YK89",
    "externalRequestId": "FXI9222877130",
    "benchmarkRate": 0,
    "dealtAmount": 1000000,
    "settledAmount": 1186240,
    "baseAmount": 1000000,
    "termAmount": 1186240,
    "spotRate": 1.18624,
    "rate": 1.18624,
    "regulatory": { … },
    "fees": 0,
    "initialSettledAmount": 1186240,
    "midMarket": false,
    "upi": "EUR_USD_SPOT",
    "uti": "MCQRZU5ST1INP9222972501"
  }
]

Amend trade

Request

Amend a verified trade by amount, rate, customer, or all three. Available to broker users and sales dealer users.

You must specify at least one property in addition to id.

Work with your Integral Technical Account Manager to configure the following trade amendment restrictions:

  • Number of minutes during which a trade is eligible for amendment after verification.
  • Total number of price amend requests allowed for a trade. Each request to change a rate property (spotRate, forwardPoints) counts against the total allowed.
  • Maximum amount a trade can be amended expressed as a percentage of the trade’s size. If you specify dealtAmount, the value must be greater than zero and less than this maximum.
Bodyapplication/json
idstring[ 5 .. 30 ] charactersrequired

ID of the verified trade to amend.

dealtAmountnumber(double)>= 0.01

New amount of the dealt instrument. Must be greater than zero and less than the maximum percentage change allowed, if configured.

customerAccountstring[ 1 .. 30 ] characters

New customer’s legal entity ID.

forwardPointsnumber(double)

New forward points for a forward or NDF trade.

spotRatenumber(double)

New spot rate of the trade. Must be greater than zero.

notestring<= 255 characters

Any notes on the trade. These notes are sent via STP if the trade is eligible for STP (stp=true).

application/json

Amend a trade by customer, rate, and amount.

{
  "id": "FXI9271593184",
  "spotRate": 1.18631,
  "dealtAmount": 21000,
  "customerAccount": "BrokerCustOrg1le1",
  "forwardPoints": 0.0001,
  "note": "Sales: done after cover"
}

Responses

The ID of the amended trade.

Bodyapplication/json
originalTradeIdstring[ 5 .. 30 ] characters

ID of the original trade that was amended.

tradeIdstring[ 5 .. 30 ] characters

ID of the new trade.

createdTimestring<= 32 characters

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

Response
application/json
{
  "originalTradeId": "string",
  "tradeId": "string",
  "createdTime": "string"
}

Roll trade

Request

Roll a trade to another value date. Available to broker users and sales dealer users.

Bodyapplication/json
idstring[ 5 .. 30 ] charactersrequired

ID of the trade to roll.

forwardPointsnumber(double)required

Forward points for the rolled trade.

Default 0
valueDatestring= 10 charactersrequired

New value date for the rolled trade in the format YYYY-MM-DD.

fixingDatestring= 10 characters

New fixing date for the rolled NDF trade in the format YYYY-MM-DD. Required for trades in non-deliverable instruments.

notestring<= 255 characters

Any notes on the trade. These notes are sent via STP if the trade is eligible for STP (stp=true).

application/json

Roll a trade to a forward date.

{
  "id": "FXI9339324216",
  "forwardPoints": 0.0002,
  "valueDate": "2024-10-05",
  "note": "Daily roll"
}

Responses

The ID and creation time of the book trade in Integral’s system.

Bodyapplication/json
originalTradeIdstring[ 5 .. 30 ] characters

ID of the original trade that was rolled.

Example: "FXI30500922"
tradeIdstring[ 5 .. 30 ] characters

ID of the new trade.

Example: "FXI30501001"
createdTimestring<= 32 characters

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

Example: "2025-01-10 12:36:27,200 +0000"
Response
application/json
{
  "originalTradeId": "FXI30500922",
  "tradeId": "FXI30501001",
  "createdTime": "2025-01-10 12:36:27,200 +0000"
}

Allocate trade

Request

Divide a trade into post-trade allocations among multiple legal entities of the same organization. Available to broker users and sales dealer users. Customer organizations can be configured to allocate trades.

You must ensure that the allocated amounts equal the original trade amount.

Bodyapplication/json
idstring[ 5 .. 30 ] charactersrequired

ID of the verified trade to divide into allocations.

allocationsArray of objects(tradeAllocateObject)required
allocations[].​referenceIdstring[ 1 .. 120 ] charactersrequired

Your reference ID for the allocation. Must be unique in the scope of the allocate request. Not validated for global uniqueness.

allocations[].​allocationAmountnumber(double)>= 0.01required

Size of the allocation.

allocations[].​sidestring<= 10 charactersrequired

The direction of the allocation from the perspective of the customerAccount (case sensitive):

  • BUY
  • SELL
allocations[].​customerAccountstring[ 1 .. 30 ] charactersrequired

The customer account of the allocation.

allocations[].​notestring<= 255 characters

Any notes on the allocation. These notes are sent via STP if the trade is eligible for STP (stp=true).

application/json

Divide a trade amongst multiple organizations.

{
  "id": "FXI9270827222",
  "allocations": [
    { … },
    { … }
  ]
}

Responses

Original trade ID and allocation IDs.

Bodyapplication/json
originalTradeIdstring[ 5 .. 30 ] characters

ID of the original trade that was amended.

tradesArray of objects
Response
application/json
{
  "originalTradeId": "FXI9270827222",
  "trades": [
    { … },
    { … }
  ]
}

Cancel trades

Request

Cancel individual trades by trade ID or one or more trades by your trade request.

You must specify either tradeId or clientRequestId.

If you specify tradeId, all other parameters are ignored.

Bodyapplication/json
tradeIdstring[ 5 .. 30 ] characters

ID of trade to cancel. If specified, all other parameters are ignored.

clientRequestIdstring[ 5 .. 255 ] characters

Your reference ID for the request to trade that resulted in the trades you want to cancel. Multiple trades may be cancelled.

customerOrgstring[ 1 .. 60 ] charactersrequired

ID of the customer organization on the trade.

application/json

Cancel a single trade by trade ID.

{
  "customerOrg": "BrokerCustOrgDle5",
  "tradeId": "FXI73879011"
}

Responses

Success.

Bodyapplication/json
One of:
customerOrgstring

ID of the customer organization on the cancelled trade.

tradeIdstring

ID of cancelled trade.

Response
application/json
{
  "customerOrg": "string",
  "tradeId": "string"
}

Query trade by trade ID

Request

Get trade details for a given trade ID.

Path
idstring<= 32 charactersrequired
Example: FXI9222877182
No request payload

Responses

The trade object. If empty, no trade matched the given Integral trade ID.

Bodyapplication/json
orderIdstring<= 60 characters

Order ID.

tradeIdstring<= 255 characters

Integral trade ID.

tradeTypestring<= 20 characters

Trade type:

  • Spot
  • Outright
  • Swap
  • FwdFwd
  • NDF
  • NDFSwap
tenorstring<= 20 characters

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
tradeDatestring<= 20 characters

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

valueDatestring<= 20 characters

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.

executionTimestring<= 32 characters

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

makerboolean
  • 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).
orderSidestring<= 10 characters

Side of the order from your perspective, either Buy or Sell.

statusstring<= 32 characters

Status of the trade when the message was created:

  • Pending
  • Verified
  • Rejected
rejectReasonstring<= 128 characters

The reason for trade rejection, if any.

symbolstring<= 35 characters

Dealt instrument pair (currency, metal, energy, index, crypto), seven-character ISO code (for example, AUD/USD).

dealtInsstring<= 17 characters

Dealt instrument, three-character ISO code (for example, AUD).

dealtAmountnumber(double)

Amount of the dealt instrument or near-leg instrument.

settledAmountnumber(double)

Amount of the settlement instrument.

baseAmountnumber(double)

Amount of base instrument.

termAmountnumber(double)

Amount of term instrument.

spotRatenumber(double)

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

ratenumber(double)

All-in rate.

orderTypestring<= 20 characters

Type of order.

rateIdstring<= 255 characters

ID of the originating rate, if any.

forwardPointsnumber(double)

Forward points for outright trades and near leg of swaps.

swapPointsnumber(double)

Swap points, if any.

customerAccountstring<= 30 characters

Customer legal entity ID.

customerOrgstring<= 30 characters

Customer org ID.

traderstring<= 30 characters

Customer trader user who did the trade.

counterpartystring<= 30 characters

Counterparty ID.

cptyLongNamestring<= 128 characters

Counterparty name.

coverTradeIdsArray of strings

List of ID for trades that cover this trade, if any.

cptyTradeIdstring or null<= 255 characters

Trade ID assigned by counterparty.

counterpartyAccountstring<= 30 characters

Counterparty legal entity ID.

channelstring<= 100 characters

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

farTenorstring<= 20 characters

Far-leg tenor for swaps.

farFixingTenorstring<= 20 characters

Far-leg fixing tenor for NDF swaps.

farFixingDatestring<= 20 characters

Far-leg fixing date for NDF swaps in the format YYYY-MM-DD.

farValueDatestring<= 20 characters

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

farSidestring<= 10 characters

Side of the far leg for swaps.

farRatenumber(double)

Far-leg rate for swaps.

farDealtAmountnumber(double)

Far-leg amount in the dealt instrument for swaps.

farSettledAmountnumber(double)

Far-leg amount in the settlement instrument for swaps.

farBaseAmountnumber(double)

Far-leg amount in the base instrument for swap.

farTermAmountnumber(double)

Far-leg amount in the term instrument for swaps.

farForwardPointsnumber(double)

Far-leg forward points for swaps.

counterpartyALEIstring<= 100 characters

LEI code for counterpartyA.

counterpartyBLEIstring<= 100 characters

LEI code for counterpartyB.

externalRequestIdstring<= 255 characters

The ID of the originating request for price from a system external to Integral.

requestIdstring<= 255 characters

The ID of the originating request for price from Integral systems.

portfolioIdstring<= 100 characters

Containing portfolio ID for batch trades and SSPs.

benchmarkRatenumber(double)

Reference benchmark rate.

outrightobject

Forward pricing info for the trade.

farLegISINstring<= 12 characters

Far-leg International Securities Identification Number for multi-leg trades.

nearLegISINstring<= 12 characters

Near-leg International Securities Identification Number for multi-leg trades.

regulatoryobject

An object containing regulatory information.

feesnumber(double)

Fees on the trade, if any.

initialSettledAmountnumber(double)

The initial settled amount before any amendment.

notesstring<= 255 characters

Any notes on the order entered by the order submitting user.

midMarketboolean

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

utistring<= 150 characters

The Unique Trade Identifier if the trade was done in a SEF.

upistring<= 50 characters

The Unique Product Identifier if the trade was done in a SEF.

isinLinkIdstring<= 12 characters

International Securities Identification Number link ID.

Response
application/json
{
  "orderId": "4820926010",
  "tradeId": "FXI9222877182",
  "tradeType": "Spot",
  "tenor": "SPOT",
  "tradeDate": "2022-03-01",
  "valueDate": "2022-03-03",
  "maker": false,
  "orderSide": "Sell",
  "status": "Verified",
  "symbol": "EUR/USD",
  "dealtIns": "EUR",
  "customerAccount": "pfOrg",
  "customerOrg": "pfOrg",
  "trader": "DealerUser",
  "counterparty": "CptyA",
  "cptyLongName": "Counterparty A",
  "coverTradeIds": [
    "FXI9222877182C"
  ],
  "cptyTradeId": "FXI9222877182C",
  "counterpartyAccount": "CptyA_LE",
  "channel": "API/REST/ESP",
  "externalRequestId": "Spot3442",
  "benchmarkRate": 0,
  "dealtAmount": 1000000,
  "settledAmount": 1186310,
  "baseAmount": 1000000,
  "termAmount": 1186310,
  "spotRate": 1.18631,
  "rate": 1.18631,
  "fees": 0,
  "initialSettledAmount": 1186310,
  "midMarket": false,
  "upi": "EUR_USD_SPOT",
  "uti": "MCQRZU5ST1INP9222877182"
}

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

Reference data

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

Operations