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.

claim/asset

Assets that have been transferred need to be claimed by the recipient. This method creates the claim transaction.

claim/raw

Raw assets that have been transferred need to be claimed by the recipient. This method creates the claim transaction.

claim/readonly

Readonly assets that have been transferred need to be claimed by the recipient. This method creates the claim transaction.

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	Used to identify the session to invoke the command under. For single-user API mode the session should not be supplied	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	Used to identify the session to invoke the command under. For single-user API mode the session should not be supplied	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 for lookup	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	Used to identify the session to invoke the command under. For single-user API mode the session should not be supplied	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"
   }
 ]