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.

contracts

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.