# REST API 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](#section/Authentication-options%2FToken-based-authentication) - [HMAC authentication](#section/Authentication-options%2FHMAC-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](#operation/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](#operation/renewToken). 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: {% table %} - Header attribute {% width="10%" %} - Description --- - Authorization - The base64-encoded signature. --- - Date - A date and time as [standard UTC string](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Date). --- - Digest - `SHA-256=base64(sha256())` If there is no request body, `Digest` should be set to the digest of a body of 0 length. --- - type - Set to `hmac`. {% /table %} 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 {% table %} - Parameter {% width="15%" %} - 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. {% /table %} ### 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. {% table %} - HTTP code {% width="15%" %} - 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. {% /table %} 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. {% table %} - Reason code {% width="55%" %} - 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. {% /table %} Version: 1.0.1 License: Integral ## Servers ``` https://3ac93db9-6290-458d-9482-0dc0a0e9607a.remockly.com ``` ## Security ### SSO_TOKEN API key to authorize requests. Type: apiKey In: header Name: SSO_TOKEN ## Download OpenAPI description [REST API](https://docs.fxinside.net/_spec/openapi/integral-api-reference/rest.yaml) ## Authentication API Endpoints to login with token-based authentication. ### Login and get token - [POST /v2/sso/login](https://docs.fxinside.net/openapi/integral-api-reference/rest/authentication-api/login.md): Use the ID and password issued to you to login and generate and refresh/renew an access token. All REST API calls should pass this token to access authenticated services. The access token is in of the response header. Your token is valid for a limited time. ### Renew token - [GET /v2/sso/token/renew](https://docs.fxinside.net/openapi/integral-api-reference/rest/authentication-api/renewtoken.md): To keep your session alive, use the ID and password issued to you to renew your token. If your token is expired, you are issued a new token. ## Market data Endpoints to get prices, indicative rates, benchmark rates, and trade ticker rates. ### Get spot rate by symbol - [GET /v2/rates/spot](https://docs.fxinside.net/openapi/integral-api-reference/rest/market-data/getspotrate.md): 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. ### Get spot rate by type and symbol - [GET /v2/rates/spot/{type}](https://docs.fxinside.net/openapi/integral-api-reference/rest/market-data/getspotratebytype.md): 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. ### Get spot rate by type and symbol for organization - [GET /v2/rates/spot/{type}/{org}](https://docs.fxinside.net/openapi/integral-api-reference/rest/market-data/getspotratebytypeorg.md): 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. ### Get market data - [GET /marketdataset](https://docs.fxinside.net/openapi/integral-api-reference/rest/market-data/getmarketdataset.md): 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: * : you must include the ID of a regular MDS. * : you must omit this parameter for regular rates. If you specify the of a regular MDS and the parameter, an error is returned. * : you must include either or . If neither is included, an error is returned. * : you must include either or . If neither is included, an error is returned. #### 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 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: * : you must include the ID of an end-of-day MDS. * : you must omit this parameter for end-of-day rates. If you specify the of a end-of-day MDS and the parameter, an error is returned. * : you must include either or . If neither is included, an error is returned. * : you must include either or . If neither is included, an error is returned. #### 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 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: * : you must include either or . Do not include both. Specify the MDS ID for fixed-period rates from a specific fixed-period MDS. * : you must include either or . 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 #### 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 ### Get benchmark - [GET /v2/benchmark](https://docs.fxinside.net/openapi/integral-api-reference/rest/market-data/getbenchmark.md): Get the Integral FX benchmark rate for a given symbol. ### Get ticker - [GET /v2/ticker](https://docs.fxinside.net/openapi/integral-api-reference/rest/market-data/getticker.md): Get the last traded price for a given symbol. ## Orders Place, cancel, and query orders. ### Place order - [POST /v2/orders](https://docs.fxinside.net/openapi/integral-api-reference/rest/orders/placeorder.md): Place a new order. You can place various types of order such as limit, market, at best, previously quoted, stop, algo, pegged, and more. Under algo orders you can execute various strategies such as TWAP. Returns status code 202 if your order is accepted by the system for processing. Use the query order endpoints to get the current status of your order Query order (client ID or all active orders) or Query order (server ID). You can get all trades associated with an order using Query all trades on an order by ID. Trades contain information like counterparty, settlement date, and amount. ### Required request attributes for all order types All place-order requests must have the following attributes: - - - - - - ### Conditionally required request attributes and values Your request may require additional attributes based on the order type or attribute values. For example, if you place an order with (good-til-canceled) you must also specify . | Order type | Required attributes and values | |-|-| | Limit(IOC) | , , | | Limit(GTC) | , , | | Limit(GTT) | , , , | | Market(IOC) | , , | | At best | , , | | Stop | , , , execFlags=BidTrigger|OfferTrigger|MidTrigger | | Previously quoted | , , , | | Algo (TWAP) | , , | | On behalf of | , , | ### Query order (client ID or all active orders) - [GET /v2/orders](https://docs.fxinside.net/openapi/integral-api-reference/rest/orders/queryorderbyclientid.md): Get the order for the given client order ID. Omit the request parameter to return all active orders. ### Cancel all orders - [DELETE /v2/orders](https://docs.fxinside.net/openapi/integral-api-reference/rest/orders/cancelallorders.md): With best effort, cancel all active orders. This may require you to make the request multiple times until all of the open active orders are cancelled. You can call Query order (client ID or all active orders) to check if any order is still active. ### Query order (server ID) - [GET /v2/orders/{id}](https://docs.fxinside.net/openapi/integral-api-reference/rest/orders/queryorderbyserverid.md): Get the order for the given server order ID. ### Cancel individual order - [DELETE /v2/orders/{id}](https://docs.fxinside.net/openapi/integral-api-reference/rest/orders/cancelorder.md): Cancel a single active order by ID (the unique ID assigned by server, received in the place order response). Use Query order (server ID) or Query order (client ID or all active orders) to get the current status of your order. ## 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). ### Book trade - [POST /v2/trades](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/booktrade.md): Enter trades done in other systems. ### Query all trades on an order by ID - [GET /v2/trades](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/queryorderallfills.md): Get all fills for the order ID assigned by Integral returned in the or field when the order was placed. ### Amend trade - [POST /v2/trades/amendment](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/tradeamend.md): 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 . 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 (, ) counts against the total allowed. * Maximum amount a trade can be amended expressed as a percentage of the trade’s size. If you specify , the value must be greater than zero and less than this maximum. ### Roll trade - [POST /v2/trades/roll](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/traderoll.md): Roll a trade to another value date. Available to broker users and sales dealer users. ### Allocate trade - [POST /v2/trades/allocations](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/tradeallocate.md): 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. ### Cancel trades - [POST /v2/trades/cancel](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/tradecancel.md): Cancel individual trades by trade ID or one or more trades by your trade request. You must specify either or . If you specify , all other parameters are ignored. ### Query trade by trade ID - [GET /v2/trades/{id}](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/querytrade.md): Get trade details for a given trade ID. ## RFS/RFQ The RFS/RFQ endpoints provide 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](/openapi/integral-api-reference/rest/rfsrfq/quoterequest#rfsrfq/quoterequest/t=request&path=rfq) property to `false`. * Set the [expiry](/openapi/integral-api-reference/rest/rfsrfq/quoterequest#rfsrfq/quoterequest/t=request&path=expiry) property 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](/openapi/integral-api-reference/rest/rfsrfq/quoterequest#rfsrfq/quoterequest/t=request&path=rfq) property to `true`. * Set the [expiry](/openapi/integral-api-reference/rest/rfsrfq/quoterequest#rfsrfq/quoterequest/t=request&path=expiry) property 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. ### Request quote - [POST /v2/rfs](https://docs.fxinside.net/openapi/integral-api-reference/rest/rfsrfq/quoterequest.md): Send a quote request to receive firm quotes from liquidity providers for the specified symbol, tenor, amount, and direction (bid, ask, two-way) for a given price type. After the initial success response , you must query the status of your request to receive the latest quotes and status (see Query quote request (server ID) and Query quote request (client ID)). When you receive a quote, you can then accept it (Accept quote). ### Query quote request (client ID) - [GET /v2/rfs](https://docs.fxinside.net/openapi/integral-api-reference/rest/rfsrfq/queryrequestclientid.md): Query the state of quote request by the RFS ID assigned by you when you sent the request. The response can include quotes, trades, and state of the Quote request. ### Query quote request (server ID) - [GET /v2/rfs/{requestId}](https://docs.fxinside.net/openapi/integral-api-reference/rest/rfsrfq/queryrequestserverid.md): Query the state of quote request by the RFS ID assigned by Integral. The response can include quotes, trades, and state of the Quote request. ### Accept quote - [POST /v2/rfs/{requestId}](https://docs.fxinside.net/openapi/integral-api-reference/rest/rfsrfq/acceptquote.md): Accept a quote from liquidity providers that you requested (Request quote). ### Withdraw quote request - [DELETE /v2/rfs/{requestId}](https://docs.fxinside.net/openapi/integral-api-reference/rest/rfsrfq/withdrawquoterequest.md): Withdraw an active quote request. ## Positions Get open positions. ### Positions - [GET /v2/positions](https://docs.fxinside.net/openapi/integral-api-reference/rest/positions/getpositions.md): Get open positions. All parameters are optional. If no parameters are specified, all open positions for the logged-in user are returned. ### Positions by value date - [GET /v2/positions/{valueDate}](https://docs.fxinside.net/openapi/integral-api-reference/rest/positions/getpositionsvaluedate.md): 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. ## Custody Custody operations. ### Get deposit address - [GET /custody/v2/deposit/address](https://docs.fxinside.net/openapi/integral-api-reference/rest/custody/getdepositaddress.md): Get the deposit address on a native blockchain which is used to link deposits to specific customer wallets. ### Query deposit history - [GET /custody/v2/deposit/history](https://docs.fxinside.net/openapi/integral-api-reference/rest/custody/getdeposithistory.md): Query the deposit history for current customer ### Initiate withdrawal - [POST /custody/v2/withdraw/apply](https://docs.fxinside.net/openapi/integral-api-reference/rest/custody/createwithdrawal.md): Withdraw a digital asset from a customer wallet. ### Query withdrawal history - [GET /custody/v2/withdraw/history](https://docs.fxinside.net/openapi/integral-api-reference/rest/custody/getwithdrawhistory.md): Query withdrawal transaction history for current user. Transactions are sorted by . ## Accounts Account-related data and operations, such as checking balances. ### Get account balance - [GET /custody/v2/account/balances](https://docs.fxinside.net/openapi/integral-api-reference/rest/accounts/getaccountbalance.md): Get account balances in a specific asset or all assets. ### Get broker account balance - [GET /custody/v2/broker/account/balances](https://docs.fxinside.net/openapi/integral-api-reference/rest/accounts/getbrokeraccountbalance.md): Get broker account balances in a specific asset or all assets. ### Update broker account balance - [PUT /custody/v2/broker/account/balances](https://docs.fxinside.net/openapi/integral-api-reference/rest/accounts/updatebrokeraccountbalance.md): Update broker account balances in a specific asset or all assets. ## 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](#operation/resend) endpoint. ### Get done trades - [GET /v2/trades/stp/messages](https://docs.fxinside.net/openapi/integral-api-reference/rest/stp-download/gettrades.md): 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. ### Prepare trades to resend - [POST /v2/trades/stp/resend](https://docs.fxinside.net/openapi/integral-api-reference/rest/stp-download/resend.md): Set previously downloaded trades with within the specified date range as eligible for download. You must then call the Get trades endpoint to download the trades. The attribute on previously downloaded trades is always set to . ## Reference data Fundamental business data (such as accounts, assets, and symbols) used by multiple endpoints. ### Get list of assets - [GET /custody/v2/asset/assetDetail](https://docs.fxinside.net/openapi/integral-api-reference/rest/reference-data/getassetdetail.md): List of all assets with details, such as whether you can deposit or withdraw, minimum withdrawal amount, and withdrawal fee. Use the parameter to get details of a specific asset.