# Integral Developers ## Table of contents - [What/Why/How?](https://docs.fxinside.net/.github/pull_request_template.md) - [Alternative sidebars](https://docs.fxinside.net/developer-portal/sidebar-alternative.md) - [Market Data](https://docs.fxinside.net/developer-portal/websocket-market-data.md) - [Account balances](https://docs.fxinside.net/developer-portal/websocket-account-balances.md) - [FIX Market Data API](https://docs.fxinside.net/developer-portal/fix-market-data.md) - [FIX Market Data API with Incremental Refresh](https://docs.fxinside.net/developer-portal/fix-market-data-incr.md) - [Credit balances](https://docs.fxinside.net/developer-portal/websocket-credit-balances.md) - [FIX Maker API: ESP Workflow](https://docs.fxinside.net/developer-portal/fix-maker-esp.md) - [Integral FIX API: your gateway to global liquidity](https://docs.fxinside.net/fix.md) - [FIX Orders API](https://docs.fxinside.net/developer-portal/fix-orders.md) - [FIX Maker API: RFS Workflow](https://docs.fxinside.net/developer-portal/fix-maker-rfs.md) - [Positions](https://docs.fxinside.net/developer-portal/websocket-positions.md) - [FIX STP API](https://docs.fxinside.net/developer-portal/fix-stp.md) - [RFS](https://docs.fxinside.net/developer-portal/websocket-rfs.md) - [FIX Advanced Orders API](https://docs.fxinside.net/developer-portal/fix-orders-advanced.md) - [WebSocket API](https://docs.fxinside.net/developer-portal/websocket.md) - [Login](https://docs.fxinside.net/developer-portal/tutorials/tutorialauth.md) - [Integral APIs](https://docs.fxinside.net/developer-portal/apis.md) - [Orders](https://docs.fxinside.net/developer-portal/websocket-orders.md) - [FIX RFS API](https://docs.fxinside.net/developer-portal/fix-rfs.md) - [Book a trade](https://docs.fxinside.net/developer-portal/tutorials/tutorialbooktrade.md) - [Get fixed-period market data](https://docs.fxinside.net/developer-portal/tutorials/tutorialfixedperiodmds.md) - [Get spot prices](https://docs.fxinside.net/developer-portal/tutorials/tutorialgetesp.md) - [Get done trades](https://docs.fxinside.net/developer-portal/tutorials/tutorialgettrades.md) - [Place an order (at best)](https://docs.fxinside.net/developer-portal/tutorials/tutorialplaceorderatbest.md) - [Place an order (limit)](https://docs.fxinside.net/developer-portal/tutorials/tutorialplaceorderlimit.md) - [Place an order (previously quoted)](https://docs.fxinside.net/developer-portal/tutorials/tutorialplaceorderpq.md) - [Request quotes](https://docs.fxinside.net/developer-portal/tutorials/tutorialrfs.md) - [Trade fixed-period rates](https://docs.fxinside.net/developer-portal/tutorials/tutorialwkflwfixedperiodmds.md) - [Trade on behalf of](https://docs.fxinside.net/developer-portal/tutorials/tutorialwkflwtradeonbehalf.md) - [Trade RFS](https://docs.fxinside.net/developer-portal/tutorials/tutorialwkflwtraderfs.md) - [Trade ESP spot](https://docs.fxinside.net/developer-portal/tutorials/tutorialwkflwtradespot.md) - [Release Notes API](https://docs.fxinside.net/openapi/release-notes-api.md): API for managing release notes, versions, and products - [Streetlights Kafka API](https://docs.fxinside.net/asyncapi/websocket/streetlights-kafka-asyncapi.md): The Smartylighting Streetlights API allows you to remotely manage the city lights. ### Check out its awesome features: * Turn a specific streetlight on/off ๐ŸŒƒ * Dim a specific streetlight ๐Ÿ˜Ž * Receive real-time information about environmental lighting conditions ๐Ÿ“ˆ - [Warehouse Positions](https://docs.fxinside.net/asyncapi/websocket/warehouse-positions.md): The Integral Warehouse Positions API is a WebSocket API that provides real-time updates of warehouse positions via event-driven communication between client and server. Users subscribe to a channel to start receiving messages. All the messages are encoded as JSON objects. The Warehouse Positions API is private and requires authentication. After successful authentication users can connect to the websocket endpoint `/v2/warehouse` using the `wss` protocol. - [REST API](https://docs.fxinside.net/openapi/integral-api-reference/rest.md): 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 %}