Hive Engine Platform Developer Documentation. logo

Market

See definitions:

Actions:
Action: createSSC

Create SSC

JSON Example

Also see: createSSC

Action: cancel

cancel

JSON Example
{
  "contractName": "market",
  "contractAction": "cancel",
  "contractPayload": {
    "type": "buy",
    "id": "a47906faa9071cf524e0bc8909b0d6f81f4fd48f"
  }
}

Also see: cancel

Action: buy

buy

JSON Example
{
  "contractName": "market",
  "contractAction": "buy",
  "contractPayload": {
    "symbol": "BEE",
    "quantity": "1",
    "price": "0.00000001"
  }
}

Also see: buy

Action: sell

sell

JSON Example
{
  "contractName": "market",
  "contractAction": "sell",
  "contractPayload": {
    "symbol": "BEE",
    "quantity": "100000",
    "price": "1"
  }
}

Also see: sell

Action: marketBuy

market buy

JSON Example

Also see: marketBuy

Action: marketSell

market sell

JSON Example

Also see: marketSell

Nft

Token issuance

Once an NFT has been created, its data properties defined, and editing permissions set, it’s time to issue some tokens!

fees

There is a fee per each token issued, which the issuing account or smart contract must pay. The issuer can choose to pay the fee in one of several different regular Hive Engine token types. Initially, such fees will be payable in BEE. The issuance fee is calculated as follows:

fee = base fee + ((base fee) x (number of data properties))

The base fee when paying with BEE is 0.001. The fee reflects the fact that on-chain storage has a cost, so the more data properties an NFT has, the higher the issuance fee will be per token.

Example: you want to issue 3 tokens and pay the fees in BEE. Your NFT has 4 data properties. You will pay 0.005 BEE per token issued (the base fee of 0.001, plus an additional 0.001 for each data property). The total cost to issue 3 tokens will be 0.015 BEE.

locked tokens

When a token is issued, the issuer can optionally choose to lock up a basket of other tokens within the issued NFT token (or NFT instance, as we sometimes refer to them). These locked tokens will be transferred from the issuing account or smart contract, and considered “owned” by the newly issued token itself. The locked tokens will stay attached to the issued NFT instance for the duration of its lifetime. Locked tokens cannot be spent or interacted with in any way, they are effectively out of circulation.

The only way to retrieve locked tokens is by burning the NFT instance that contains them. When an NFT token is burned, any locked tokens are released & transferred back to the account or smart contract that held the burned token (they are NOT sent back to the issuing account!).

Thus locked tokens are a way to give intrinsic value to an NFT, above & beyond what the NFT is worth in its own right. Token holders are incentivized to burn their NFTs in order to get back the value of the tokens locked within.

Note that both regular Hive Engine tokens and other NFT instances can be locked within tokens in this manner. You can even have a mix of different token types.

locked token restrictions

For performance reasons, the following rules apply when dealing with locked tokens. For the purposes of these rules, we use the term container token to refer to an NFT instance that contains other NFT instances locked within it (an NFT instance that only contains regular Hive Engine tokens is NOT considered to be a container token).

Token IDs are always represented as strings when used in arguments to contract actions. Note that ID numbers are not globally unique; they will only be unique for a given symbol (i.e. MYNFT can have a token with id 5, and OTHERNFT can also have a token with id 5). The combination of symbol and ID number uniquely identifies a token (or NFT instance, as we sometimes refer to them).

See definitions:

Actions:
Action: createSSC

Create SSC

JSON Example

Also see: createSSC

Action: create

Creates a new NFT. A creation fee of 100 BEE is required.

JSON Example
{
  "contractName":"nft",
  "contractAction":"create",
  "contractPayload":{
    "symbol":"TESTNFT",
    "name":"My Test NFT"
  }
}
{
  "contractName":"nft",
  "contractAction":"create",
  "contractPayload":{
    "symbol":"TESTNFT",
    "name":"My Test NFT",
    "url":"https://mynft.com",
    "maxSupply":"1000"
  }
}
{
  "contractName":"nft",
  "contractAction":"create",
  "contractPayload":{
    "symbol":"TESTNFT",
    "name":"My Test NFT",
    "orgName":"My Company Inc",
    "productName":"Uber Cool Product",
    "url":"https://mynft.com",
    "maxSupply":"1000",
    "authorizedIssuingAccounts":[
      "cryptomancer",
      "aggroed",
      "harpagon"
    ],
    "authorizedIssuingContracts":[
      "mycontract",
      "myothercontract"
    ]
  }
}

Also see: create

Action: updateUrl

Updates the url of the token’s project web site.

JSON Example
{
  "contractName": "nft",
  "contractAction": "updateUrl",
  "contractPayload": {
    "symbol": "TESTNFT",
    "url": "https://mynewurl.com"
  }
}

Also see: updateUrl

Action: updateMetadata

update metadata

JSON Example
{
  "contractName": "nft",
  "contractAction": "updateMetadata",
  "contractPayload": {
    "symbol": "TESTNFT",
    "metadata": {
      "url": "https://mycoolnft.com",
      "icon": "https://mycoolnft.com/token.jpg",
      "desc": "This NFT will rock your world! It has features x, y, and z. So cool!"
    }
  }
}

Also see: updateMetadata

Action: updateName

Updates the user friendly name of an NFT.

JSON Example
{
  "contractName":"nft",
  "contractAction":"updateName",
  "contractPayload":{
    "symbol":"TESTNFT",
    "name":"My Awesome NFT"
  }
}

Also see: updateName

Action: updateOrgName

Updates the name of the company/organization that manages an NFT.

JSON Example
{
  "contractName":"nft",
  "contractAction":"updateOrgName",
  "contractPayload":{
    "symbol":"TESTNFT",
    "orgName":"Nifty Company Inc"
  }
}

Also see: updateOrgName

Action: updateProductName

Updates the name of the product/brand that an NFT is associated with.

JSON Example
{
  "contractName":"nft",
  "contractAction":"updateProductName",
  "contractPayload":{
    "symbol":"TESTNFT",
    "productName":"Acme Exploding NFTs"
  }
}

Also see: updateProductName

Action: addAuthorizedIssuingAccounts

Adds blockchain accounts to the list of accounts that are authorized to issue new tokens on behalf of the NFT owner. This will NOT replace the existing list; it only adds to it. There is a maximum limit of 10 accounts that can be on this list.

JSON Example
{
   "contractName":"nft",
   "contractAction":"addAuthorizedIssuingAccounts",
   "contractPayload":{
      "symbol":"TESTNFT",
      "accounts":[
         "satoshi",
         "aggroed",
         "cryptomancer"
      ]
   }
}

Also see: addAuthorizedIssuingAccounts

Action: addAuthorizedIssuingContracts

Adds smart contracts to the list of contracts that are authorized to issue new tokens on behalf of the NFT owner. This will NOT replace the existing list; it only adds to it. There is a maximum limit of 10 smart contracts that can be on this list.

JSON Example
{
    "contractName": "nft",
    "contractAction": "addAuthorizedIssuingContracts",
    "contractPayload": {
        "symbol": "TESTNFT",
        "contracts": [ "mycontract","anothercontract","mygamecontract" ]
    }
}

Also see: addAuthorizedIssuingContracts

Action: removeAuthorizedIssuingAccounts

Removes blockchain accounts from the list of accounts that are authorized to issue new tokens on behalf of the NFT owner. This will NOT replace the existing list; it only removes from it.

JSON Example
{
   "contractName":"nft",
   "contractAction":"removeAuthorizedIssuingAccounts",
   "contractPayload":{
      "symbol":"TESTNFT",
      "accounts":[
         "satoshi",
         "aggroed"
      ]
   }
}

Also see: removeAuthorizedIssuingAccounts

Action: removeAuthorizedIssuingContracts

Removes smart contracts from the list of contracts that are authorized to issue new tokens on behalf of the NFT owner. This will NOT replace the existing list; it only removes from it.

JSON Example
{
   "contractName":"nft",
   "contractAction":"removeAuthorizedIssuingContracts",
   "contractPayload":{
      "symbol":"TESTNFT",
      "contracts":[
         "mycontract",
         "mygamecontract"
      ]
   }
}

Also see: removeAuthorizedIssuingContracts

Action: transferOwnership

Transfers ownership of an NFT from the current owner to another blockchain account.

JSON Example
{
   "contractName":"nft",
   "contractAction":"transferOwnership",
   "contractPayload":{
      "symbol":"TESTNFT",
      "to":"aggroed"
   }
}

Also see: transferOwnership

Action: addProperty

Adds a new data property schema to an existing NFT definition. For every data property added beyond the third, a 100 BEE fee is required.

Note that once a data property name and type are set, they normally CANNOT be changed (however under some limited circumstances this is possible; see updatePropertyDefinition). Also, data property schemas cannot be deleted once added.

JSON Example
{
   "contractName":"nft",
   "contractAction":"addProperty",
   "contractPayload":{
      "symbol":"TESTNFT",
      "name":"color",
      "type":"string"
   }
}
{
   "contractName":"nft",
   "contractAction":"addProperty",
   "contractPayload":{
      "symbol":"TESTNFT",
      "name":"edition",
      "type":"number",
      "isReadOnly":true
   }
}
{
   "contractName":"nft",
   "contractAction":"addProperty",
   "contractPayload":{
      "symbol":"TESTNFT",
      "name":"isPremium",
      "type":"boolean",
      "authorizedEditingAccounts":[
         "cryptomancer"
      ],
      "authorizedEditingContracts":[
         "mycontract",
         "myothercontract"
      ]
   }
}

Also see: addProperty

Action: setPropertyPermissions

Can be used after calling the addProperty action to change the lists of authorized editing accounts & contracts for a given data property. There is a maximum limit of 10 accounts/contracts that can be on each list.

JSON Example
{
   "contractName":"nft",
   "contractAction":"setPropertyPermissions",
   "contractPayload":{
      "symbol":"TESTNFT",
      "name":"color",
      "accounts":[
         "cryptomancer",
         "marc"
      ],
      "contracts":[
         
      ]
   }
}

Also see: setPropertyPermissions

Action: setProperties

Edits one or more data properties on one or more instances of an NFT.

JSON Example
{
   "contractName":"nft",
   "contractAction":"setProperties",
   "contractPayload":{
      "symbol":"TESTNFT",
      "nfts":[
         {
            "id":"573",
            "properties":{
               "color":"red",
               "level":"2"
            }
         },
         {
            "id":"301",
            "properties":{
               "level":3
            }
         }
      ]
   }
}
{
   "contractName":"nft",
   "contractAction":"setProperties",
   "contractPayload":{
      "symbol":"TESTNFT",
      "fromType":"contract",
      "nfts":[
         {
            "id":"1284",
            "properties":{
               "isFrozen":true
            }
         }
      ]
   }
}

Also see: setProperties

Action: setGroupBy

After you have created some data properties via the addProperty action, you can call setGroupBy in order to define a list of data properties by which market orders for NFT instances should be grouped by. You can think of this grouping as an index used to organize orders on the market, similar to how PeakMonsters groups Splinterlands cards according to type & gold foil status. NFT instances which have the same values for the designated data properties are considered equivalent as far as the market is concerned.

Consider the following points carefully before calling this action:

JSON Example
{
   "contractName":"nft",
   "contractAction":"setGroupBy",
   "contractPayload":{
      "symbol":"TESTNFT",
      "properties":[
         "level",
         "isFood"
      ]
   }
}

Also see: setGroupBy

Action: updatePropertyDefinition

Updates the schema of a data property. This action can be used to change a data property’s name, type, or read only attribute, with a couple caveats.

This action can only be called if no tokens for this NFT have been issued yet. Once tokens have been issued, data property schema definitions cannot be changed, and any attempt to use this action will fail. This action is primarily intended as a safeguard to protect against mistakes during NFT creation time, not for changing token characteristics later on.

JSON Example
{
   "contractName":"nft",
   "contractAction":"updatePropertyDefinition",
   "contractPayload":{
      "symbol":"TESTNFT",
      "name":"color",
      "newName":"Color"
   }
}
{
   "contractName":"nft",
   "contractAction":"updatePropertyDefinition",
   "contractPayload":{
      "symbol":"TESTNFT",
      "name":"edition",
      "type":"string"
   }
}
{
   "contractName":"nft",
   "contractAction":"updatePropertyDefinition",
   "contractPayload":{
      "symbol":"TESTNFT",
      "name":"frozen",
      "newName":"age",
      "type":"number",
      "isReadOnly":false
   }
}

Also see: updatePropertyDefinition

Action: issueMultiple

Issues multiple NFT instances at once. A maximum of 10 tokens can be issued by calling this action (there are some caveats however, see locked token restrictions). Issuance fees & other issuing behavior is same as for the issue action above.

JSON Example
// issue 3 tokens from contract -> a combination of users & contracts
{
   "contractName":"nft",
   "contractAction":"issueMultiple",
   "contractPayload":{
      "instances":[
         {
            "fromType":"contract",
            "symbol":"TSTNFT",
            "to":"aggroed",
            "feeSymbol":"ENG",
            "properties":{
               "level":0
            }
         },
         {
            "fromType":"contract",
            "symbol":"TSTNFT",
            "to":"dice",
            "toType":"contract",
            "feeSymbol":"ENG",
            "lockTokens":{
               "ENG":"5.75"
            }
         },
         {
            "fromType":"contract",
            "symbol":"TSTNFT",
            "to":"marc",
            "feeSymbol":"PAL"
         }
      ]
   }
}

Also see: issueMultiple

Action: enableDelegation

Enables the delegation feature for a token. A fee of 1000 ENG is required to perform this action.

JSON Example
{
   "contractName":"nft",
   "contractAction":"enableDelegation",
   "contractPayload":{
      "symbol":"TESTNFT",
      "undelegationCooldown":1 // 1 day to cooldown
   }
}
{
   "contractName":"nft",
   "contractAction":"enableDelegation",
   "contractPayload":{
      "symbol":"TESTNFT",
      "undelegationCooldown":30 // 30 days to cooldown
   }
}
{
   "contractName":"nft",
   "contractAction":"enableDelegation",
   "contractPayload":{
      "symbol":"TESTNFT",
      "undelegationCooldown":91 // 13 weeks to cooldown
   }
}

Also see: enableDelegation

Action: delegate

Delegates one or more tokens to another account or smart contract. Can only be called if an NFT has previously had delegation enabled through the enableDelegation action. If a token is already delegated, it cannot be delegated again until it has been undelegated.

A maximum of 50 tokens can be delegated in a single call of this action. Note that tokens cannot be delegated to the null account.

JSON Example

Also see: delegate

Action: undelegate

undelegate

JSON Example
// user -> user
{
   "contractName":"nft",
   "contractAction":"delegate",
   "contractPayload":{
      "to":"cryptomancer",
      "nfts":[{"symbol":"TSTNFT", "ids":["200"]}, {
        "symbol":"DRAGON",
        "ids":["1", "1000", "10000", "9999"]
      }]
   }
}
// user -> contract
{
   "contractName":"nft",
   "contractAction":"delegate",
   "contractPayload":{
      "to":"splinterlands",
      "toType":"contract",
      "nfts":[{"symbol":"TSTNFT", "ids":["200"]}, {
        "symbol":"DRAGON",
        "ids":["1", "1000", "10000", "9999"]
      }]
   }
}
// contract -> contract
{
   "contractName":"nft",
   "contractAction":"delegate",
   "contractPayload":{
      "to":"splinterlands",
      "toType":"contract",
      "fromType":"contract",
      "nfts":[{"symbol":"DRAGON", "ids":[ "111", "112"]}]
   }
}
// contract -> user
{
   "contractName":"nft",
   "contractAction":"delegate",
   "contractPayload":{
      "to":"aggroed",
      "toType":"user", // could have omitted this, but including it here for clarity
      "fromType":"contract",
      "nfts":[{"symbol":"NFTNFT", "ids":[ "987654"]}]
   }
}

Also see: undelegate

Action: transfer

Transfers one or more tokens to another account or smart contract.

A maximum of 50 tokens can be transferred in a single call of this action. Note that tokens cannot be transferred if they are currently being delegated to another account. Also, tokens cannot be transferred to null; for that you need to use the burn action.

JSON Example
// user -> user
{
    "contractName": "nft",
    "contractAction": "transfer",
    "contractPayload": {
        "to": "cryptomancer",
        "nfts": [
            {"symbol":"TSTNFT", "ids":["200"]},
            {"symbol":"DRAGON", "ids":["1","1000","10000","9999"]}
        ]
    }
}
// user -> contract
{
    "contractName": "nft",
    "contractAction": "transfer",
    "contractPayload": {
        "to": "splinterlands",
        "toType":"contract",
        "nfts": [
            {"symbol":"TSTNFT", "ids":["200"]},
            {"symbol":"DRAGON", "ids":["1","1000","10000","9999"]}
        ]
    }
}
// contract -> contract
{
    "contractName": "nft",
    "contractAction": "transfer",
    "contractPayload": {
        "to": "splinterlands",
        "toType":"contract",
        "fromType":"contract",
        "nfts": [
            {"symbol":"DRAGON", "ids":["111","112"]}
        ]
    }
}
// contract -> user
{
    "contractName": "nft",
    "contractAction": "transfer",
    "contractPayload": {
        "to": "aggroed",
        "toType":"user",      // could have omitted this, but including it here for clarity
        "fromType":"contract",
        "nfts": [
            {"symbol":"NFTNFT", "ids":["987654"]}
        ]
    }
}
// A successful transfer action will emit a "transfer" event for each token transferred: from: original token holder, fromType: u or c, to: new token holder, toType: u or c, symbol, id example:
{
    "contract": "nft",
    "event": "transfer",
    "data": {
        "from": "aggroed",
        "fromType": "u",
        "to": "cryptomancer",
        "toType": "u",
        "symbol": "TEST",
        "id": "1000"
    }
}

Also see: transfer

Action: burn

Burns one or more tokens. When a token is burned, it is sent to the null account and the circulating supply of that NFT is reduced by 1. In addition, any locked tokens contained within the burned token will be released and transferred back to the account that held the burned token.

A maximum of 50 tokens can be burned in a single call of this action. Note that tokens cannot be burned if they are currently being delegated to another account. There are some additional caveats, see locked token restrictions.

JSON Example
{
    "contractName": "nft",
    "contractAction": "burn",
    "contractPayload": {
        "nfts": [ {"symbol":"TESTNFT", "ids":["666"]} ]
    }
}
{
    "contractName": "nft",
    "contractAction": "burn",
    "contractPayload": {
        "fromType": "contract",
        "nfts": [
            {"symbol":"TESTNFT", "ids":["12","45","882"]},
            {"symbol":"MYNFT", "ids":["672","33"]},
            {"symbol":"DRAGON", "ids":["123456"]}
        ]
    }
}
// A successful burn action will emit a "burn" event for each token burned: account: who burned it, ownedBy: u or c, unlockedTokens: released regular token list, unlockedNfts: released NFT instance list, symbol, id example:

{
    "contract": "nft",
    "event": "burn",
    "data": {
        "account": "aggroed",
        "ownedBy": "u",
        "unlockedTokens": {"ENG":"15", "TKN":"0.75"},
        "unlockedNfts": [{"symbol": "TSTNFT", "ids": ["1","2"]}, {"symbol": "OTHERNFT", "ids": ["320"]}],
        "symbol": "TSTNFT",
        "id": "305"
    }
}

Also see: burn

Tokens

See definitions:

Actions:
Action: createSSC

Also see: createSSC

Action: updateParams
JSON Example
{
  "tokenCreationFee": "100",
  "enableDelegationFee": "1000",
  "enableStakingFee": "1000"
}

Also see: updateParams

Action: updateUrl

Update the url of a token

Also see: updateUrl

Action: updateMetadata

Update the metadata of a token

JSON Example
{
  "contractName": "tokens",
  "contractAction": "updateMetadata",
  "contractPayload": {
    "symbol": "YOUR_SYMBOL",
    "metadata": {
      "url": "",
      "icon": "",
      "desc": ""
    }
  }
}

Also see: updateMetadata

Action: updatePrecision

Update the precision of a token (it can only be increased)

JSON Example
{
  "contractName": "tokens",
  "contractAction": "updatePrecision",
  "contractPayload": {
    "symbol": "YOUR_SYMBOL",
    "precision": 8
  }
}

Also see: updatePrecision

Action: transferOwnership

Transfer ownership of a token from the current token issuer to an other account

JSON Example
{
  "contractName": "tokens",
  "contractAction": "transferOwnership",
  "contractPayload": {
    "symbol": "YOUR_SYMBOL",
    "to": "alice"
  }
}

Also see: transferOwnership

Action: create

Creates a token (a token creation fee might be enforced)

JSON Example
{
  "contractName": "tokens",
  "contractAction": "create",
  "contractPayload": {
    "symbol": "ORB",
    "name": "Essence Orbs",
    "precision": 0,
    "maxSupply": "200000",
    "url": "https://splinterlands.com"
  }
}

Also see: create

Action: issue

Issue tokens to an account (can only be triggered by the account that created the token)

JSON Example
{
  "contractName": "tokens",
  "contractAction": "issue",
  "contractPayload": {
    "symbol": "YOUR_SYMBOL",
    "to": "alice",
    "quantity": "10000"
  }
}

Also see: issue

Action: issueToContract

Also see: issueToContract

Action: transfer

Transfer tokens to an account

JSON Example
{
  "contractName": "tokens",
  "contractAction": "transfer",
  "contractPayload": {
    "symbol": "BEE",
    "to": "hive-tokens",
    "quantity": "1000",
    "memo": ""
  }
}

Also see: transfer

Action: transferToContract

Transfer tokens to a contract

JSON Example
{
  "contractName": "tokens",
  "contractPayload": {
    "symbol": "BEE",
    "quantity": "300",
    "to": "crittermanager"
  },
  "contractAction": "transferToContract"
}

Also see: transferToContract

Action: transferFromContract

Transfer from contract

Also see: transferFromContract

Action: checkPendingUnstakes

check pending unstakes

Also see: checkPendingUnstakes

Action: enableStaking

Enables the staking feature for a token.

JSON Example
{
  "contractName": "tokens",
  "contractAction": "enableStaking",
  "contractPayload": {
    "symbol": "YOUR_SYMBOL",
    "unstakingCooldown": 14,
    "numberTransactions": 2
  }
}

Also see: enableStaking

Action: stake

Stakes tokens. (if it is a token that allows staking)

JSON Example
{
  "contractName": "tokens",
  "contractAction": "stake",
  "contractPayload": {
    "to": "alice",
    "symbol": "BEE",
    "quantity": "0.125"
  }
}

Also see: stake

Action: stakeFromContract

Also see: stakeFromContract

Action: unstake

Unstakes tokens. (if it is a token that allows staking) There is a cooldown period that is setup per token (see “enableStaking” action)

JSON Example
{
  "contractName": "tokens",
  "contractAction": "unstake",
  "contractPayload": {
    "symbol": "YOUR_SYMBOL",
    "quantity": "10"
  }
}

Also see: unstake

Action: cancelUnstake

Cancels an initiated unstake.

JSON Example
{
  "contractName": "tokens",
  "contractAction": "cancelUnstake",
  "contractPayload": {
    "txID": "df21a5311af93b4440e7ecca6d59d2ac7c7845eb"
  }
}

Also see: cancelUnstake

Action: enableDelegation

Enables the delegation feature for a token.

JSON Example
{
  "contractName": "tokens",
  "contractAction": "enableDelegation",
  "contractPayload": {
    "symbol": "YOUR_SYMBOL",
    "undelegationCooldown": 10
  }
}

Also see: enableDelegation

Action: delegate

Delegates tokens. (if it is a token that allows delegation) If a delegation already exists for that account it will add the new quantity to it (to decrease a delegation you need to undelegate)

JSON Example
{
  "contractName": "tokens",
  "contractAction": "delegate",
  "contractPayload": {
    "to": "alice",
    "symbol": "YOUR_SYMBOL",
    "quantity": "25"
  }
}

Also see: delegate

Action: undelegate

Undelegates tokens partially or totally. (if it is a token that allows delegation) There is a cooldown period that is setup per token (see “enableDelegation” action)

JSON Example
{
  "contractName": "tokens",
  "contractAction": "undelegate",
  "contractPayload": {
    "from": "alice",
    "symbol": "BEE",
    "quantity": "15"
  }
}

Also see: undelegate

Action: checkPendingUndelegations

check pending undelegations

Also see: checkPendingUndelegations