Nexus Dev
Search…
βš™
Tritium Overview
Tritium API Overview
Nexus provides several APIs to allow users and developers to easily interact with the functionality of the Nexus software stack. Each API is a logically grouped collection of methods that either interact with a specific part of the stack (e.g. ledger, registers), by functional area (accounts, assets, tokens), or by industry specific use case (supply, music).

Protocol

The API server uses the HTTP protocol and supports both GET and POST request methods.
The API's use JSON (JavaScript Object Notation) as their primary data transport mechanism for both input and output. However the API server also supports URL encoded requests (application/x-www-form-urlencoded).

Port

By default the API server runs on port 8080. This can be changed by setting apiport=xxxx in your nexus.conf or starting your daemon with the -apiport=xxxx parameter.

Security

The Nexus API uses the HTTP Basic authentication scheme. This requires the caller to set an Authorization HTTP header with the value Basic <credentials> with the <credendtials> portion set to apiuser:apipassword and base64 encoded. On the API server side the authentication is configured by adding apiuser=<username> and apipassword=<password> to the nexus.conf. NOTE: If you wish to disable authentication entirely, you can do so by setting apiauth=0 in your nexus.conf
The authentication mechanism is complemented by the implementation of SSL encryption (HTTPS). By default the API server is started with SSL disabled. To enable it, please add apissl=1 to your nexus.conf

Multi-user Sessions

The Nexus API can be configured to run in multiuser mode, allowing multiple signature chains to be logged in and use the API simultaneously. This feature can be enabled by setting multiuser=1 in your nexus.conf (default off). When multiuser is enabled, the initial login response will include a session ID value. This session ID must be then be included in all subsequent API calls to endpoints that require a user to be logged in.

Endpoint

Each API endpoint can be invoked through the following semantics:
<api>/<verb>/<noun>
e.g.
1
http://127.0.0.1:8080/ledger/get/block
Copied!
NOTE: URI's are always in lowercase.

Verbs (actions)

The following list of verbs are used throughout the Nexus APIs. While the action is generic in nature (i.e. list, get, create), implementations of these actions will adhere to certain semantics or mandatory parameters regardless of the noun (resource).
  • list
    • Retrieves a sorted list of objects or data
    • Sorting is based on transaction/object age, by default is always newest to oldest. Some list methods support additional sort fields.
    • Supported parameters:
      • order : The order of the results. Values can be desc (default) or asc
      • limit : The number of records to return, default 100.
      • page: Allows the results to be returned by page (zero based). E.g. passing in page=1 will return the second set of (limit) transactions. The default value is 0 if not supplied.
      • offset : An alternative to page, offset can be used to return a set of (limit) results from a particular index.
      • verbose : to indicate the verbosity of the data returned. Values can be default, summary, or detail
  • get
    • Retrieves a single object or piece of data
    • Supported parameters:
      • (No common parameters)
  • create
    • Creates a single resource / object
    • Supported parameters:
      • format indicates the format of the data being provided to create the item / object (where applicable). Values can be basic, raw, JSON, XML, and ANSI C
  • debit
  • create
  • transfer
  • claim
  • reverse
  • buy
  • sell
  • login
  • logout
  • unlock
  • lock
  • subscribe
​
​

Nouns (resources)

Within each API endpoint, a noun is used to describe the resource or object upon which the action is taking place.
The commonly used resources are described below:
  1. 1.
    transaction :
    A transaction is a cryptographic object that contains the contracts that operated on the registers. It is indexed by an uint512_t, so any index used must be sanitized to this format.
  2. 2.
    block :
    A block is a cryptographic object that contains the transactions in a specific sequence of time. It is indexed by an uint1024_t, so any index used must be sanitized to this format. A block index is prepended with 0x to imply hexadecimal encoding. Base-16 encoding is all that is supported at present. Other forms of encoding may be supported at a later time (possibly base-58).
  3. 3.
    account :
    An account is an object register of the following types: trust or base. It is responsible for holding the state of a user's account balance.
  4. 4.
    object :
    An object is a register with nType being REGISTER::OBJECT. An object is always parsed, and access to it's data members given.
  5. 5.
    token :
    A token is an object register of standard OBJECT::TOKEN. It contains the domain parameters of a token such as supply or total number of significant digits.
  6. 6.
    asset :
    An asset is an object register of a specialized type.

Error Handling

In the event that an API call results in an error, a JSON object will be returned with the following format:
1
{
2
"error" :
3
{
4
"code" : -123,
5
"message" : "An error has occurred"
6
}
7
}
Copied!

DSL Error Codes

Code
Message
1
Query Syntax Error: duplicate wildcard not allowed
2
Query Syntax Error: only '=' and '!=' operator allowed for type [typename]
3
Query Syntax Error: malformed where clause at [clause]
4
Query Syntax Error: must use = with no extra characters.
5
Query Syntax Error: must use '(' and ')' to mix AND/OR statements
6
Query Syntax Error: missing logical operator for group
7
Query Syntax Error: empty where clause at [clause]
8
​
9
​

API Error Codes

Code
Message
-1
Method not available: [message]
-2
Method not found: [message]
-3
Method was deprecated at version [version]: [message]
-4
API not found (API name)
-5
Object not available: [message]
-6
content-type [content type] not supported
-7
Unsupported type [type] for parameters.
-8
Unable to Extract Input Address
-9
Session (session) doesn't exist
-10
Invalid session ID
-11
User not logged in
-12
Malformed or missing object encoding for [type]
-13
Object not found
-14
Malformed request URL
-15
Object is not an account or token
-16
Account has not been unlocked for transactions
-17
Failed to create transaction
-18
Invalid format for standard [name]
-19
Field [name] doesn't exist in object
-20
Field [name] is read-only and can't be updated