Dev:API - Assets
An asset is a user-defined data structure or NFT that is stored in a register, owned by a given profile. Assets can hold one or more pieces of data and users can define the fields (name, data, type, mutability) that data is stored in.
Supported Nouns
The following nouns are supported for this API command-set:
Noun | Description |
---|---|
any | Any asset, raw, or readonly register |
asset | An editable register with type safety |
raw | An editable register without type safety |
readonly | A non-editable register without type safety |
schema | An asset template for user-defined standards |
Example
You can include more than one noun for a command if you separate them by a comma. The following command will return all the assets of type asset, raw, and readonly that the session profile owns.
assets/list/asset,raw,readonly
Supported Verbs
The following verbs are currently supported by this command-set:
Verb | Description | Nouns |
---|---|---|
claim | Claim ownership of a register | any, asset, raw, readonly |
create | Generate a register of specified type | asset, raw, readonly, schema |
get | Get register of supported type | any, asset, raw, readonly, schema |
history | Generate the history of all last states | any, asset, raw, readonly, schema |
list | List all registers owned by active session | any, asset, raw, readonly, partial, schema |
tokenize | To represent ownership of an asset object with a token object | asset |
transactions | List all transactions that modified specified object | any, asset, raw, readonly, schema |
transfer | Transfer a specified register | any, asset, raw, readonly |
update | Update a specified object | any, asset, raw, readonly, schema |
verify | Verify if a given register has been tokenized | partial |
Example
The following will show you how to invoke a basic <verb>/<noun> URI. This will return all the assets of type any that the session profile owns.
assets/list/any
Supported Operators
The following verbs are currently supported by this command-set:
Operator | Description |
---|---|
array | Returns an array of values from the filtered data-set |
count | Returns the total number of occurrences of a value in the filtered data-set |
floor | Strips the decimal off of a value or array of values |
max | Returns the largest value in the filtered data-set |
mean | Returns the average value of the filtered data-set |
min | Returns the smallest value in the filtered data-set |
mode | Returns the most occurring value in the filtered data-set |
sum | Returns the sum of all the values in the filtered data-set |
Example
The following will show you how to invoke a basic <verb>/<noun>/<field>/<operator> URI. This will calculate the average value of the modified field for all assets owned by active session:
assets/list/any/modified/mean
Supported Formats
When creating or modifying a register, a format is required to encode the operations to the given register. The following formats are supported for this command-set:
Format | Description |
---|---|
readonly | Takes string argument data=, creates raw state |
raw | Takes string argument data=, creates or updates raw state |
basic | Takes all additional string arguments as key=value, updates or creates fields of object with string type |
json | akes string argument json=<json>, updates or creates fields of object for any type and mutability |
Please see the Formats page to learn how to use the above formats in more details.
Verbs
claim
This method will claim ownership of the asset to complete the corresponding transfer transaction.
assets/claim/noun
This command supports the asset, raw and readonly nouns.
Parameters
Name | Description | Required |
---|---|---|
name | Allows the user to rename an item when it is claimed. By default the name is copied from the previous owner and a Name record is created for the item in your user namespace. If you already have an object for this name then you will need to provide a new name in order for the claim to succeed. | no |
pin | PIN for this profile. | Required if locked. |
session | User session ID | Required if argument -multiuser=1 is set |
txid | the transaction ID (hash) of the asset transfer transaction for which is being claimed. | yes |
Return Values
Name | Description |
---|---|
success | Boolean flag indicating whether the asset claim was successful. |
txid | The ID (hash) of the transaction that includes the claimed asset. |
Example Response JSON
{ "success": true, "txid": "01f35304d41d00b002ca02d3bd9cf6cfeb134f5c454d4b6f5a355e35ffc557cfb3756834f3cf5cbeaf98da6773adcaaeca80154d15e449d4876ddf35c0b895cf" }
create
Create a new object register specified by given noun.
assets/create/noun
The supported nouns for this command are asset, raw, readonly, and schema.
NOTE: There is a limit of 1KB for asset data to be saved in the register, excluding the asset name. There is a fee of 1 NXS for creating and an asset and an additional 1 NXS for the optional name object.
Parameters
If any of the required parameters are not set, the command will fail with an error response designating the missing parameters.
Name | Description | Required |
---|---|---|
format | Required to identify the format used to define the asset. Values can be readonly, raw, basic and JSON. | yes |
name | A UTF-8 encoded string that will generate a name object register that points to new object. This will cost an additional 1 NXS if on the mainnet. | no |
pin | This is the PIN that was used when creating master profile. | Required if not unlocked for transactions |
session | User session ID | Required if argument -multiuser=1 is set |
Return Values
Name | Description |
---|---|
address | The register address for the register that was just created. |
success | Boolean flag indicating whether the asset was created successfully. |
txid | The hash of the transaction that was generated for this tx. |
Example Response JSON
The following object will be returned under the JSON object results if the command succeeded:
{ "success": true, "address": "87VmNhitFJv3WA3Yrovt9A3hts2MoXcfExyy9LiXyhK1sdThwYM", "txid": "01230bbc8f0d72aaaff13471e34520d17902290de9a1e5ce1f320f0883024e2d96e21b59a3e48b8d2b5ba2874e93d5d3b4f412e06dc92440c2e12682c958fe34" }
get
Retrieves information for an asset and returns a JSON structured object with the fields. You must choose the correct noun in order to have command execute.
assets/get/noun
The supported nouns for this command are any, asset, raw, readonly, or schema. If you are unsure of the correct noun then you can use the any keyword, or aggregate nouns using the comma as separator.
Parameters
If any of the required parameters are not set, the command will fail with an error response designating the missing parameters.
Name | Description | Required |
---|---|---|
address | register address of the asset | Required if name is not provided |
name | In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. | Required if address is not provided |
pin | This is the PIN that was used when creating master profile. | Required if not unlocked for transactions |
session | User session ID | Required if argument -multiuser=1 is set |
Return Values
Name | Description |
---|---|
address | The register address that is currently assigned to given asset. |
created | The UNIX timestamp when the asset was created. |
data | If the register is raw or readonly the raw data will be returned under this key. |
<key>=<value> | If the register is asset or schema it will return the fields as key/value pairs. |
modified | The UNIX timestamp when the asset was last modified. |
name | The name that is currently pointed to the given register, if any are assigned. |
owner | The username hash of the owners profile. |
type | Asset register type. Can be OBJECT, RAW or READONLY. |
version | The serialization version of the transaction. |
Example Response JSON
[ { "owner": "b7392196b83aca438567558462cd0c5d982569c7cefa668500c4bf3e61a03b7a", "version": 1, "created": 1655279431, "modified": 1655279431, "type": "OBJECT", "Location": "Meta World ", "Owner Name": "John Doe", "Registration Details": "MRG/05/478564", "address": "87Wai2JoS4hNAEVXZVmejLS6pK21XQWKoLAkaep5aXFdrYnJJyk", "name": ":Meta_World" } ]
history
This will get the history of changes to an asset, including both the data and it's ownership.
assets/history/noun
This command supports the asset, raw, readonly and any nouns.
Parameters
Name | Description | Required |
---|---|---|
address | register address of the asset | Required if name is not provided |
name | Name of the asset in the format username:name (for local names) or namespace::name (for names in a namespace). | Required if address is not provided |
session | User session ID | Required if argument -multiuser=1 is set |
Return Values
Name | Description |
---|---|
action | MODIFY | TRANSFER | CLAIM. |
address | The register address of the asset. |
created | The UNIX timestamp when the asset was created. |
data | The data stored in a raw or readonly asset object. |
<key>=<value> | If format is basic, then the caller can provide additional = pairs for each piece of data to store in the asset. |
modified | The UNIX timestamp when the asset was last modified. |
name | The name that is currently pointed to the given register, if any are assigned. |
owner | The username hash of the owner profile. |
type | Asset register type. Can be OBJECT, RAW or READONLY. |
version | The serialization version of the transaction. |
Example Response JSON
[ { "owner": "b7a57ddfb001d5d83ab5b25c0eaa0521e6b367784a30025114d07c444aa455c0", "version": 1, "created": 1656614448, "modified": 1656614448, "type": "OBJECT", "Assetname": "Bugatti Veyron", "Chassis_No": "BV45648784634546", "Purchased Date": "22/06/2022", "Engine_No": "BVE54864660", "Owner": "John Doe", "Registration_No": "DL01EK0001", "address": "88NcYcKtMTRwtwDgfXFkZ4TbrHvkRGzsQkqVZco77Hqx1WRgCyi", "name": "local:Asset0001", "action": "CREATE" } ]
list
Retrieves a list of all the asset objects owned by the profile specified by the noun.
assets/list/noun
This command supports the any, asset, list, partial, raw, and readonly nouns. The partial noun lists partial ownership details for tokenized assets.
Parameters
Name | Description | Required |
---|---|---|
session | User session ID | Required if argument -multiuser=1 is set |
where | An array of clauses to filter the JSON results. More information can be found on Queries page. | no |
Return Values
Name | Description |
---|---|
address | The register address of the asset. |
created | The UNIX timestamp when the asset was created. |
data | The data stored in a raw or readonly asset object. |
<key>=<value> | The key-value pair for each piece of data stored in the asset. |
modified | The UNIX timestamp when the asset was last modified. |
name | The name that is currently pointed to the given register, if any are assigned. |
owner | The username hash of the owner profile. |
type | Asset register type. Can be OBJECT, RAW or READONLY. |
version | The serialization version of the transaction. |
Example Response JSON
[ { "owner": "b7392196b83aca438567558462cd0c5d982569c7cefa668500c4bf3e61a03b7a", "version": 1, "created": 1655279431, "modified": 1655279431, "type": "OBJECT", "Location": "Margoa", "Owner Name": "Ageon", "Registration Details": "MRG/05/478564", "address": "87Wai2JoS4hNAEVXZVmejLS6pK21XQWKoLAkaep5aXFdrYnJJyk", "name": "local:Asset2" } ]
tokenize
This method will tokenize an asset into fungible tokens that represent ownership:
assets/tokenize/noun
This command only supports the asset noun.
NOTE: Create the token before using tokenize.
Parameters
Name | Description | Required |
---|---|---|
address | register address of the asset to be tokenised | Required if name is not provided |
name | Name of the asset to be tokenised in the format username:name (for local names) or namespace::name (for names in a namespace). | Required if address is not provided |
pin | PIN for this profile. | Required if locked. |
session | User session ID | Required if argument -multiuser=1 is set |
token | Required to identify the token to tokenize the asset. It can be the name (for global names) username:tokenname ( for local names) or the register address of the token. |
Return Values
Name | Description |
---|---|
success | Boolean flag indicating whether the asset tokenization was successful. |
txid | The ID (hash) of the transaction that includes the asset. |
Example Response JSON
{ "success": true, "txid": "01f35304d41d00b002ca02d3bd9cf6cfeb134f5c454d4b6f5a355e35ffc557cfb3756834f3cf5cbeaf98da6773adcaaeca80154d15e449d4876ddf35c0b895cf" }
transactions
This will list off all of the transactions for the specified noun.
assets/transactions/noun
This command supports all nouns.
Parameters
Name | Description | Required |
---|---|---|
address | register address of the asset | Required if name is not provided |
name | In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. | Required if address is not provided |
session | User session ID | Required if argument -multiuser=1 is set |
verbose | determines the transaction data included in the response. Supported values are default, summary, and detail. | no |
Return Values
Name | Description |
---|---|
blockhash | The hash of the block that this transaction is included in. Blank if not yet included in a block. |
confirmations | The number of confirmations that this transaction obtained by the network. |
contracts | Described in the contracts table below. |
sequence | The sequence number of this transaction within the signature chain. |
timestamp | The Unix timestamp of when the transaction was created. |
txid | The transaction ID hash of the transaction for the credit/claim. |
type | tritium base | trust | genesis | user) |
version | The serialization version of the transaction. |
Name | Description |
---|---|
address | The register address of the asset object. |
contract | Contract ID within the transaction for the credit/claim. |
id | The sequential ID of this contract within the transaction. |
<key>=<value> | The key-value pair for each piece of data stored in the asset. |
object | The data stored in the asset. |
OP | MODIFY | TRANSFER | CLAIM. |
recipient | The transfer recipient's profile username hash. |
standard | The type of object. Can be NONSTANDARD or JSON. |
tokenized | Boolean flag indicating if the asset is tokenized or not. |
txid | The transaction ID hash of the transaction for the credit/claim. |
type | The type of register. Can be OBJECT, RAW or READONLY. |
Example Response JSON
[ { "txid": "0167d11ebea68f68e2c6591a9d94c236a60c312cf70d596492002a3e4d9a95a4f4e859c498fa6ac17c56cb4db1043abacdfd44f669112641fc4add15bb3efefa", "type": "tritium user", "version": 4, "sequence": 4, "timestamp": 1656614805, "blockhash": "9b2c063b2e8766ce9b55c5b75524b13c12c7006e0c67423dbfe1539ed4f62cd0c764f63fbbc6cb41ab9fc785ce6f88ae92e6a82e3151c4c956fa65eac524db3e1922bdced7bdd4cd97a4563dd21f011a310d062440300b2a7532fe21f6df55c7e3ba9046a982b99af97acddd768569d3cf5368cb91dcb0138cf5af7f1a6f391b", "confirmations": 95, "contracts": [ { "id": 0, "OP": "TRANSFER", "address": "88NcYcKtMTRwtwDgfXFkZ4TbrHvkRGzsQkqVZco77Hqx1WRgCyi", "recipient": "8Dnn5LUeffcRCqZLpboCHnzw5AkfwzkM5hjVScjSDHVKhFpVzCB", "tokenized": true } ] }, { "txid": "01e4eff49cadbd887511c6302d5fe8e89ead4caa87bcec2dfd55e18cb201a8fc8db9726571d3bebe554a81f579b22e2794a0e86756be326f362964e95ab28f23", "type": "tritium user", "version": 4, "sequence": 2, "timestamp": 1656614448, "blockhash": "e9b46f5dcf3c321f8a2dc672a6c47a5c6b763bc9d1f001722bc446b186afda3566f04cc739253696a3f232e036bc273ca68c18d84213186a1317d246ec86a165ba152838a2eca4425c19472dc8fb1b762f4413c5a633c4fef5494378b9858da34129dcd5bc556110c1e79aa42f01f8bae6f4938a6e87a63b6d30e2ee6025d507", "confirmations": 97, "contracts": [ { "id": 0, "OP": "CREATE", "address": "88NcYcKtMTRwtwDgfXFkZ4TbrHvkRGzsQkqVZco77Hqx1WRgCyi", "type": "OBJECT", "standard": "NONSTANDARD", "object": { "Assetname": " Bugatti Veyron", "Chassis_No": "BV45648784634546", "Purchased Date": "22/06/2022", "Engine_No": "BVE54864660", "Owner": "John Doe", "Registration_No": "DL01EK0001" } } ] } ]
transfer
This will initiate ownership transfer of the specified noun:
assets/transfer/noun
This command supports the asset, raw and readonly nouns.
Parameters
Name | Description | Required |
---|---|---|
address | Register address of the asset | Required if name is not provided |
expires | Number of seconds until the transaction can no longer be claimed by the recipient | no |
name | In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. | Required if address is not provided |
pin | PIN for this profile. | Required if locked. |
recipient | The profile username or genesis hash of the recipient account | |
session | User session ID | Required if argument -multiuser=1 is set |
Return Values
Name | Description |
---|---|
address | Register address of the asset |
success | Boolean flag indicating whether the asset transfer was successful. |
txid | The ID (hash) of the transaction that includes the asset transfer. |
Example Response JSON
{ "success": true, "address": "87VmNhitFJv3WA3Yrovt9A3hts2MoXcfExyy9LiXyhK1sdThwYM", "txid": "01bc48f80792fd4b97d43555d5993f0edfb0998ab14bcf159404f52e34a64abd6769f61014f006703100aa040a27aca65227133b2b5a71617efac3bc5640e361" }
update
This method provides the user with the ability to update the object data specified by the noun:
assets/update/noun
This command only supports the asset and raw nouns.
Parameters
Name | Description | Required |
---|---|---|
address | Register address of the asset | Required if name is not provided |
data | input for the data object | Required if format is readonly or raw |
format | Format of the asset to update. Values can be readonly, raw, basic and JSON. | yes |
<key>=<value> | 'key=value' pairs to update each piece of data for the asset for format basic | no |
name | In the format username:name (for local names) or namespace::name (for names in a namespace). If you are logged in, the username: field is not required. | Required if address is not provided |
pin | PIN for this profile. | Required if locked. |
session | User session ID | Required if argument -multiuser=1 is set |
Return Values
Name | Description |
---|---|
success | Boolean flag indicating whether the asset was saved successfullly. |
txid | The ID (hash) of the transaction that includes the asset transfer. |
Example Response JSON
{ "success": true, "txid": "01bc48f80792fd4b97d43555d5993f0edfb0998ab14bcf159404f52e34a64abd6769f61014f006703100aa040a27aca65227133b2b5a71617efac3bc5640e361" }
verify
Verify if a given register has been tokenized.
assets/verify/partial
This command only supports the partial noun.