Nexus Dev

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).


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).


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.


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.


Each API endpoint can be invoked through the following semantics:
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:
"error" :
"code" : -123,
"message" : "An error has occurred"

DSL Error Codes

Query Syntax Error: duplicate wildcard not allowed
Query Syntax Error: only '=' and '!=' operator allowed for type [typename]
Query Syntax Error: malformed where clause at [clause]
Query Syntax Error: must use = with no extra characters.
Query Syntax Error: must use '(' and ')' to mix AND/OR statements
Query Syntax Error: missing logical operator for group
Query Syntax Error: empty where clause at [clause]

API Error Codes

Method not available: [message]
Method not found: [message]
Method was deprecated at version [version]: [message]
API not found (API name)
Object not available: [message]
content-type [content type] not supported
Unsupported type [type] for parameters.
Unable to Extract Input Address
Session (session) doesn't exist
Invalid session ID
User not logged in
Malformed or missing object encoding for [type]
Object not found
Malformed request URL
Object is not an account or token
Account has not been unlocked for transactions
Failed to create transaction
Invalid format for standard [name]
Field [name] doesn't exist in object
Field [name] is read-only and can't be updated
Field [name] size exceeds maximum length [size]
Field [name] is a reserved field name
Object standard [name] not available for command
No orders found for market
Market order invalid contract: message
Invalid parameter [from], [type] requires correct token
Malformed base64 encoding
Missing parameter [name] for command
Unsupported format [type] specified
Operations failed to execute
Ledger failed to sign transaction
Failed to accept
Incorrect or missing name / address
Asset not found
Invalid parameter [key=type], expecting [type]
Unsupported type [name] for command
Missing token name / address
Missing asset name / address
Missing name_from / address_from
Previous transaction not found
Invalid transaction-id
No valid debits to buy from
No valid contracts in tx
Transaction failed to build
Missing name_to / address_to
Missing amount
Missing price
Token not found
Unsupported type for name/address
Missing txid
No available token accounts for recipient
No more available accounts for debit
Missing name / address of account to credit
Missing name_proof / address_proof to credit
Must have at least two recipients to debit from any
Invalid user-type enum [value]
Invalid Parameter [name]
Empty Parameter [name]
Account to credit is not a NXS account
[name] out of range [max]
Proof account is for a different token than the asset token
Coinbase transaction mined by different user
Could not retrieve default NXS account to credit
Missing recipient account name_to / address_to
Object is not an account
Cannot use aggregate fieldnames with operations
-safemode next hash mismatch, broadcast terminated
Amount too small
Insufficient funds
Trust account not found
Fieldname [name] doesn't exist
Register is not a trust account
Trust account is not a NXS account
No registers found
Value [key=value] exceeds dataset size [size]
Cannot set stake for trust account until after Genesis transaction
Insufficient trust account balance to add to stake
Stake not changed
getblockhash requires the daemon to be started with the -indexheight flag
Missing height
[command] cannot use parameter [name] combined with [name]
Block number out of range
Block not found
Missing hash or height
getblock by height requires the daemon to be started with the -indexheight flag
Missing hash or txid
Invalid or unknown transaction
Missing or empty name
Invalid register_address
Namespace already exists
Missing name / register_address
Name not found
Missing namespace name
Invalid namespace
Namespace does not exist: [namespace]
Cannot create name in [namespace] you don't own
An object with this name already exists in this namespace
An object with this name already exists for this user
Transfer transaction not found
Missing username prefix before name
Unknown name: (name)
Invalid address
Missing register_address parameter
Object not found
Missing address
Invalid name / address
No history found
Failed to read transaction
Specified name/address is not of type (type)
Contract execution failed
Missing genesis / username
Missing username / destination
Destination user doesn't exist
(type) not found
Name / address is not of type (type)
Cannot transfer names created without a namespace
Item not found
[type] operator not supported for this command-set
[name] field(s) does not exist for result
Maximum number of contracts exceeded (99), please try again or use -autotx mode.
Aggregated type [noun] not allowed for [verb]
Invalid operator [op] for command.
[type] unsupported for operator [op]
Operator [op] cannot be used on empty result
Token not found
Address is not for a NXS account"
Missing username
Missing password
Missing PIN
Account already exists
Lock not supported in multiuser mode
Account already locked
Zero-length username
Zero-length password
Zero-length PIN
Account doesn't exist
Couldn't get transaction
No previous transaction found
Invalid credentials
Already logged in with a different username
Already logged out
Username parameter not supported for this method. Names can only be obtained for the logged in user
No notifications available
No transactions found
Unlock not supported in multiuser mode
Account already unlocked for mining
Account already unlocked for transactions
Account already unlocked
Invalid PIN
Transaction rejected
Transaction already in database
Transaction contains no valid transfers
Transfer recipient object not found
Invalid field type (field)
Raw assets can not be updated
Field not found in asset (field)
Field not mutable in asset (field)
Value longer than maximum length (field)
Values must be passed in as strings
Username contains invalid characters
Name contains invalid characters
Namespace can only contain lowercase letters, numbers, periods (.)
Could not retrieve default NXS account to debit fees
Fee account is not a NXS account
Invalid address/name_to
Account is a NXS account. Please use the finance API for accessing NXS accounts.
Invalid reference
Invalid expiration time
Names cannot start with a colon
Global names cannot be created in a namespace
Global names cannot cannot contain a colon
Cannot void a transaction that does not belong to you
Cannot void debit transaction as it has already been fully credited by all recipients
Transaction contains no contracts that can be voided
Invalid supply amount. Supply must be whole number value
Invalid supply amount. The maximum token supply is 18446744073709551615
Invalid decimals amount. Decimals must be whole number value between 0 and 8
Invalid supply/decimals. The maximum supply/decimals cannot exceed 18446744073709551615
Legacy wallet is locked. walletpassphrase required
Incorrect walletpassphrase for Legacy wallet
Trust key not found for Legacy wallet
Trust key previously migrated
Previous stake transaction immature
Previous stake transaction is not a Legacy transaction
Previous transaction is not a stake transaction
Previous stake does not belong to current wallet
Could not get addresses for Legacy wallet
Trust account already has genesis
Trust account already has stake
Trust account already has trust
Username must be a minimum of 2 characters
Password must be a minimum of 8 characters
Pin must be a minimum of 4 characters
Account already unlocked for notifications
Account already unlocked for staking
Account already locked for mining
Account already locked for staking
Account already locked for transactions
Account already locked for notifications
Namespace can't be created with reserved name
Global names can't be created with reserved name
Signature chain not mature after your previous mined/stake block. X more confirmation(s) required.
Autologin user not found
Cannot set stake to a negative amount
Unable to retrieve last stake
Failed to erase expired stake change request
Failed to erase previous stake change request
Failed to save stake change request
Recipient is not a valid account
Recipient account is for a different token
Recipient object has not been tokenized
Invalid token
Cannot create transactions whilst synchronizing
Insufficient funds to pay fee
Max number of recipients (99) exceeded
recipients field must be an array
recipients array is empty
User password / pin not changed
Could not retrieve Crypto object
Missing recovery seed
Recovery seed must be a minimum of 40 characters
User create pending confirmation
Recovery seed not set on this signature chain
Missing description
Missing number
Missing reference
Missing payment account name / address
Missing sender detail
Missing recipient
Recipient user does not exist
Missing recipient detail
Missing items
Invoice must include at least one item
Missing item description
Missing item unit amount
Invalid item unit amount
Item unit amount must be greater than 0
Missing item number of units
Invalid item number of units
Item units must be greater than 0
Invoice not found
Data at this address is not an invoice
Data exceeds max register size
Data at this address is not a supply item
Cannot send invoice to self
Cannot [action] an invoice that has already been paid
Cannot [action] an invoice that has already been cancelled
Could not find invoice transfer transaction
Invoice is not yours to pay
Missing name from or address from
Account to debit is not for the required token
Cannot process notifications until peers are connected
Cannot process notifications whilst synchronizing
Contract failed peer validation
Unknown genesis
You must specify at least one unlock action
Invalid key name
Key already exists
Invalid scheme
Private keys cannot only be retrieved for keys in the crypto register
Key not yet created
Missing public key
Malformed public key
Shared key encryption only supported for EC (Brainpool) keys
Failed to generate shared key
Malformed private key
Failed to encrypt data
Failed to decrypt data
Unsupported key type
Failed to generate signature
Missing signature
Missing scheme
Error generating hash
Invalid hash function
Scheme already in use
P2P request not found
P2P server not enabled on this node
Missing App ID
Connection not found
A connection to this peer already exists
Failed to connect to peer
No messages available
Timeout waiting for peer to accept connection request
API method not supported in multiuser mode