Skip to content
API reference/
/Trades

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.

Security
SSO_TOKEN
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.

valueDatestring, <= 20 charactersrequired

Value date for the trade or near leg of swaps in the format YYYY-MM-DD.

fixingDatestring, <= 20 characters

Fixing date for NDFs in the format YYYY-MM-DD.

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.

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.

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.

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.

POST
/v2/trades
{
  "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
{
  "tradeId": "FXI30501001",
  "createdTime": "2022-01-19 12:36:27,200 +0000",
  "clientRequestId": "req swap 1"
}