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 that 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
success	Boolean flag indicating that the asset was created successfully.
address	The register address for the register that was just created.
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.
<fieldname>=<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.
<fieldname>=<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.
<fieldname>=<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"
   }
 ]