# General This section provides important information about the Notbank Exchange software. ### Websocket vs HTTP Notbank API offers a lot of flexibility as most of its methods can be invoked in both Websockets and HTTP protocol. The major difference between Websockets and HTTP is the data transmission mode. HTTP starts sending data as responses when a request is received, whereas Websockets send and receives data based on data availability. Deciding whether to use Websockets or HTTP can be tricky, several factors needs to be considered. One very important factor is the frequency of data update you need. Websockets are the best choice to handle real-time communication as they support bi-directional communication. In this model, both the client and server can push or pull data. They do not have to wait of each other and can work simultaneously. HTTP on the other hand is preferable in applications that deal with static data and are not updated regularly. ### Standard response objects and common error codes A response to an API method call usually consists of a specific response, but both successful and unsuccessful responses may consist of a generic response object that verifies only that the call was received, and not that the action requested by the call took place. A generic response to an unsuccessful call provides an error code. A generic response looks like follows: ```json { "result": true, "errormsg": null, "errorcode": 0, "detail": null } ``` | Key | Value | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | result | **boolean**. If the call has been successfully received by the OMS, result is *true*; otherwise it is *false*. | | errormsg |

string. A successful receipt of the call returns null. The errormsg key for an unsuccessful call returns one of the following messages:
- Not Authorized (errorcode 20)
- Invalid Response (errorcode 100)
- Operation Failed (errorcode 101)
- Server Error (errorcode 102)
- Resource Not Found (errorcode 104)

| | errorcode | **integer**. A successful receipt of the call returns 0. An unsuccessful receipt of the call returns one of the *errorcodes* shown in the *errormsg* list. | | detail | **string**. Message text that the system may send. The content of this key is usually *null*. | ### Notbank Node Library The [Notbank Node](https://www.npmjs.com/package/notbank) library is a JavaScript library that provides a simple interface to the Notbank API. It allows you to easily connect to the Notbank API and make requests without having to worry about the underlying details of the API. The NotbankClient class is the main entry point to the library, and it provides methods for connecting to the API, making requests, and handling responses. There are two ways to use the Notbank Node library: via Rest API or via Websockets. The library provides methods for both, allowing you to choose the one that best fits your needs. Here we provide javascript code for websocket use (using Notbank Node) and http code for Rest API use. ### Users, Accounts, and Permissions The Notbank software differentiates between *user* and *account*. A user is the person who logs in; an account represents the funds and trading that the user does — much like a bank account represents funds and checks. As with a bank account, an individual user may have multiple Exchange accounts. Similarly, multiple users may trade through a single account. There may be users who have trading access to one set of accounts that overlap (but do not duplicate) the set of accounts that another user can access. There may be a many-to-many relationship where two or more users have access to a set of accounts. The use case for this kind of "joint tenancy" is an active trading desk where a specific individual may not always be present. If User A will not be present, User B can monitor and trade on the market. User A may wish to cancel his pending trades for a specific account or instrument, but not those of his trading partner under the same account or for the same instrument. ### Permissions Permissions handle the rules that determine what a user can access and do with orders, cancellations, and the other tasks of a trading venue. Most permissions encompass tasks such as trading, depositing, or withdrawing funds. Permissions in Notbank are simplified for ease of use, for instance, API SendOrder will require the permission NotbankTrading, as almost all Trading API. In other example, CreateFiatWithdraw and TransferFunds will require the NotbankWithdraw permission. All required permisions are specified on each API method in the documentation. Some examples are: | API ENDPOINT | MINIMUM PERMISSION REQUIRED | | ------------------ | --------------------------- | | SendOrder | NotbankTrading | | CreateFiatWithdraw | NotbankWithdraw | | TransferFunds | NotbankWithdraw | | GetInstrument | Public | ### Products and Instruments In Notbank software, a ***product*** is an asset that is tradable or paid out. A product might be a national currency, a crypto-currency, or something else such as a commodity. For example, a product might be a US Dollar or a New Zealand Dollar or a Bitcoin or an ounce of gold. Transaction and withdrawal fees are denominated in products. (Products may be referred to as *assets* or currencies in some API methods). An ***instrument*** is a pair of exchanged products (or fractions of them). For example, US Dollar for Bitcoin. In conventional investment parlance, a stock or a bond is called an instrument, but implicit in that is the potential exchange of one product for another (stock for dollars). Notbank software thinks of that exchange as explicit, and separates product from instrument. (Instruments may be referred to as market pair in some API methods). ### Quotes and Orders The Notbank API includes methods related to both quotes and orders. Quoting is not enabled for the retail end user of Notbank software. Only registered market participants or *market makers* may quote. Your trading venue may offer quotes separately from orders. * A quote expresses a willingness to buy or sell at a given price. * An order is a directive to buy or sell. In this version of the Notbank matching engine software, quotes and orders are synonymous. They both can buy or sell. This is because the matching engine (like most matching engines) requires a "firm quote" — a guaranteed bid or ask. For both quotes and orders, trading priority is the same, and no preference is given one over the other. In code, the matching engine flags a quote for eventual regulatory and compliance rules, but for current software operation and trade execution, quotes and orders behave equivalently. #### Best Practices/Quotes and Orders Use the order-related API calls in preference to quote-related calls unless you specifically require quote-related calls. ### Time– and Date-Stamp Formats Notbank software uses two different time– and date-stamp formats, POSIX and Microsoft Ticks. Where the value of a time field key is an integer or long, the value is in POSIX format; when the value of a time field key is a string, it is in Microsoft Ticks format (also called *datetime*). * **POSIX** stores date/time values as the number of seconds since 1 January 1970 (long integer). Notbank software often multiples this number by 1000 for the number of milliseconds since 1 January 1970. * **Recognize POSIX format:** POSIX format is a long integer. It is usually formatted like this: `1501603632000`\
* **Microsoft Ticks** (datetime) format represents the number of ticks that have elapsed since 00:00:00 UTC, 1 January 0001, in the Gregorian calendar. A single tick represents one hundred nanoseconds (one ten-millionth of a second). There are 10,000 ticks in a millisecond; ten million ticks in a second. Ticks format does not include the number of ticks attributable to leap-seconds. * **Recognize Ticks format:** Ticks format is a string. In Notbank software, it is usually formatted like this: `"2018-08-17T17:57:56Z"` Note that a T (for time) separates the initial date from the time. The trailing Z represents the time zone, in all cases in Notbank software, this is UTC (also called Zulu time). ### The Trading Day Most Notbank installations operate 24-hour computer-based trading venues. The trading day runs from UTC Midnight to UTC Midnight (essentially, London time, but without any summertime offset), regardless of the nominal location of the venue. Values such as open or close are those values as of UTC Midnight. Values for day, month, or annual periods run from UTC Midnight to UTC Midnight. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://www.notbank.com/learn/api-reference/general.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.