# 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(<body>))` 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

## Security

### SSO_TOKEN

API key to authorize requests.

Type: apiKey
In: header
Name: SSO_TOKEN

## Download OpenAPI description

 - [REST API](https://docs.fxinside.net/_bundle/openapi/integral-api-reference/rest.yaml)

## Authentication API

 - [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 `SSO_T
 - [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

 - [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 /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 /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 provi
 - [GET /v2/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](#rt)
 - [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 /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

 - [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 TW
 - [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 `coId` to return all active 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 activ
 - [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.
 - [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)](#operation/queryOrderByServerId) or [Query order (client ID o
## Trades

 - [POST /v2/trades](https://docs.fxinside.net/openapi/integral-api-reference/rest/trades/booktrade.md): Enter trades done in other systems.
 - [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 `coId` or `orderId` field when the order was placed.
 - [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 `id`. Work with your Integral Cu
 - [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.
 - [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 allocat
 - [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 `tradeId` or `clientRequestId`. If you specify `tradeId`, all other parameters are ignored.
 - [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

 - [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 respon
 - [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 `clOrderId` assigned by you when you sent the request. The response can include quotes, trades, and state of the Quote request.
 - [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.
 - [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](#rfsrfq/quoterequest)).
 - [DELETE /v2/rfs/{requestId}](https://docs.fxinside.net/openapi/integral-api-reference/rest/rfsrfq/withdrawquoterequest.md): Withdraw an active quote request.
## 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.
 - [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

 - [Access and dashboard](https://docs.fxinside.net/openapi/integral-api-reference/rest/custody/access-and-dashboard.md): #### Access and dashboard Brokers can access the Custody system via the following UAT URL: [https://crdnet-uat.codexnetwork.org/auth/login](https://crdnet-uat.codexnetwork.org/auth/login). After loggi
 - [API authentication](https://docs.fxinside.net/openapi/integral-api-reference/rest/custody/api-authentication.md): #### API authentication The Integral Custody server provides balance APIs secured by HMAC-based authentication. Users can generate their own credentials within their Profile Settings. Please note that
 - [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.
 - [GET /custody/v2/deposit/history](https://docs.fxinside.net/openapi/integral-api-reference/rest/custody/getdeposithistory.md): Query the deposit history for current customer
 - [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.
 - [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 `createdTime`.
## Accounts

 - [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 /custody/v2/broker/account/balances](https://docs.fxinside.net/openapi/integral-api-reference/rest/accounts/getaccountbalancebroker.md): Get account balances for a broker in all assets. #### Sample script The following shell script demonstrates how to authenticate and retrieve account balances from the API. To execute this request, you
 - [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 /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 i
 - [POST /v2/trades/stp/resend](https://docs.fxinside.net/openapi/integral-api-reference/rest/stp-download/resend.md): Set previously downloaded trades with `tradeDate` within the specified date range as eligible for download. You must then call the [Get trades](#operation/getTrades) endpoint to download the trades. T
## Reference data

 - [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 `currency` parameter to get details of a specific asset.
 - [GET /v2/refdata/currencies/{instrument}](https://docs.fxinside.net/openapi/integral-api-reference/rest/reference-data/getrefdatacurrencies.md): Basic quoting convention properties of an instrument
 - [GET /v2/refdata/symbols/{symbol}](https://docs.fxinside.net/openapi/integral-api-reference/rest/reference-data/getrefdatasymbols.md): Basic quoting convention properties of a symbol
 - [GET /v2/refdata/currencies](https://docs.fxinside.net/openapi/integral-api-reference/rest/reference-data/getrefdatasymbolslist.md): Depending on the query parameter, returns: * All symbols supported in the system. * All instruments supported by the requesting organization.