Royalty Tokens

Royalty Tokens

Minting royalty tokens

POST /royaltyTokens

Mint a royalty token

Validation requirements:

  1. The sum of all balance values in holders must be equal to totalSupply.
  2. All balance values in holders must be greater than 0.

The enterprise for this track must be designated as the admin among the royalty token holders before the token is saved in the database.

  • If the enterprise (identified by its smart wallet address) is one of the holders included in the holders property of the request, that holder is designated by the server as ‘Admin’.
  • If the enterprise isn’t one of the holders, a new holder is created with the enterprise’s smart wallet address, the company name, a balance of “0” and designated as ‘Admin’.

A successful request will return the information of the newly created royalty token with its status set to validationPending

Request body

ParameterTypeDescription
assetType
required
string"track" - Is the only acceptable value at this time.
assetId
required
integerAsset ID
totalSupply
required
integerAmount of tokens being minted for the asset
holders
required
array of objectsList of holders
holders.account
required
stringWeb3 wallet adress (0x prefix followed by a long string of hexadecimal digits)
holders.friendlyName
required
stringThe name of the rights holder
holders.balance
required
numberHow many royalty tokens the holder has for this particular track

Make sure validation rule 1. applies
smartContractStandard
required
string"ERC20" - Is the only acceptable value at this time.

Example

Request
curl -X POST --header 'Content-Type: application/json' --header 'Accept: text/plain' -d '{ \ 
   "assetType": "track", \ 
   "assetId": 12345, \ 
   "totalSupply": 10, \ 
   "holders": [ \ 
     { \ 
       "account": "0x1A2B3C4D5E6F7A8B9C0D1E2F3A4B5C6D7E8F9A0", \ 
       "friendlyName": "Name", \ 
       "balance": 10 \ 
     } \ 
   ], \ 
   "smartContractStandard": "ERC20" \ 
 }' 'https://staging-api.revelator.com/royaltyTokens'
Response
{
  "royaltyTokenId": 0,
  "royaltyTokenAddress": "string",
  "enterpriseId": 0,
  "createdBy": "00000000-0000-0000-0000-000000000000",
  "createdAt": "2024-04-04T01:52:25.647Z",
  "assetType": "track",
  "assetId": 0,
  "assetMetadataJson": "string",
  "track": {
    "name": "string",
    "isrc": "string",
    "version": "string",
    "artist": {
      "artistId": 0,
      "name": "string"
    },
    "image": {
      "fileId": "00000000-0000-0000-0000-000000000000",
      "filename": "string",
      "creationDate": "2024-04-04T01:52:25.647Z",
      "lastUpdateDate": "2024-04-04T01:52:25.647Z"
    }
  },
  "holders": [
    {
      "account": "string",
      "friendlyName": "string",
      "balance": "string",
      "isAdmin": true
    }
  ],
  "smartContractStandard": "ERC20",
  "status": "validationPending",
  "royaltyTokenURI": "string",
  "network": "string",
  "fees": "string",
  "asset": {
    "type": "string",
    "assetURI": "string",
    "ownerURI": "string",
    "artist": "string",
    "name": "string",
    "description": "string",
    "bpm": 0,
    "duration": 0,
    "key": "string",
    "genre": "string",
    "image": "string",
    "artistImageURL": "string",
    "spotifyId": "string",
    "appleId": 0,
    "trackMimeType": "string",
    "artworkMimeType": "string",
    "tags": [
      "string"
    ],
    "locationCreated": "string",
    "external_url": [
      {
        "name": "string",
        "url": "string"
      }
    ],
    "animation_url": "string",
    "youtube_url": "string",
    "originalReleaseDate": "string",
    "recordLabel": "string",
    "publisher": "string",
    "upc": "string",
    "isrc": "string",
    "lyrics": "string",
    "language": "string",
    "attributes": [
      {
        "trait_type": "string",
        "value": "string"
      }
    ],
    "credits": [
      {
        "name": "string",
        "creditType": "string"
      }
    ],
    "releases": [
      {
        "releaseType": "string",
        "releaseTitle": "string",
        "artist": "string",
        "releaseDate": "string",
        "recordLabel": "string",
        "upc": 0,
        "imageURL": "string"
      }
    ],
    "platform": {
      "name": "string",
      "imageURL": "string",
      "assetId": "string",
      "enterpriseId": "string"
    }
  }
}

Retrieving Royalty Tokens

GET /royaltyTokens

Retrieves all royalty tokens associated with the account.

Query params

Query ParamTypeDescription
pageNumber
optional
integerPagination page number.
pageSize
optional
integerPagination page size.
orderByProperty
optional
stringProperty to order the results by. (Possible values: createdAt, status)
orderByDescending
optional
booleantrue - descending
false - ascending
royaltyTokenStatus
optional
array of stringsRetrieve only results matching these statuses
fromDate
optional
date-timeA starting date-time string in the ISO8601 standard
toDate
optional
date-timeAn ending date-time string in the ISO8601 standard
searchText
optional
stringAny text to search for
royaltyTokenIds
optional
array of integersRetrieve only results matching these tokenIds

Example

Request
curl -X GET --header 'Accept: text/plain' 'https://staging-api.revelator.com/royaltyTokens?pageNumber=1&pageSize=10'
Response
{
  "totalItemsCount": 0,
  "pageNumber": 0,
  "pageSize": 0,
  "items": [
    {
      "royaltyTokenId": 0,
      "royaltyTokenAddress": "string",
      "enterpriseId": 0,
      "createdBy": "00000000-0000-0000-0000-000000000000",
      "createdAt": "2024-04-04T01:52:25.643Z",
      "assetType": "track",
      "assetId": 0,
      "assetMetadataJson": "string",
      "track": {
        "name": "string",
        "isrc": "string",
        "version": "string",
        "artist": {
          "artistId": 0,
          "name": "string"
        },
        "image": {
          "fileId": "00000000-0000-0000-0000-000000000000",
          "filename": "string",
          "creationDate": "2024-04-04T01:52:25.643Z",
          "lastUpdateDate": "2024-04-04T01:52:25.643Z"
        }
      },
      "holders": [
        {
          "account": "string",
          "friendlyName": "string",
          "balance": "string",
          "isAdmin": true
        }
      ],
      "smartContractStandard": "ERC20",
      "status": "validationPending",
      "royaltyTokenURI": "string",
      "network": "string",
      "fees": "string",
      "asset": {
        "type": "string",
        "assetURI": "string",
        "ownerURI": "string",
        "artist": "string",
        "name": "string",
        "description": "string",
        "bpm": 0,
        "duration": 0,
        "key": "string",
        "genre": "string",
        "image": "string",
        "artistImageURL": "string",
        "spotifyId": "string",
        "appleId": 0,
        "trackMimeType": "string",
        "artworkMimeType": "string",
        "tags": [
          "string"
        ],
        "locationCreated": "string",
        "external_url": [
          {
            "name": "string",
            "url": "string"
          }
        ],
        "animation_url": "string",
        "youtube_url": "string",
        "originalReleaseDate": "string",
        "recordLabel": "string",
        "publisher": "string",
        "upc": "string",
        "isrc": "string",
        "lyrics": "string",
        "language": "string",
        "attributes": [
          {
            "trait_type": "string",
            "value": "string"
          }
        ],
        "credits": [
          {
            "name": "string",
            "creditType": "string"
          }
        ],
        "releases": [
          {
            "releaseType": "string",
            "releaseTitle": "string",
            "artist": "string",
            "releaseDate": "string",
            "recordLabel": "string",
            "upc": 0,
            "imageURL": "string"
          }
        ],
        "platform": {
          "name": "string",
          "imageURL": "string",
          "assetId": "string",
          "enterpriseId": "string"
        }
      }
    }
  ],
  "additionalCounters": {}
}

GET /royaltyTokens/{tokenId}

Retrieves a royalty token by its unique tokenId

Example

Request
curl -X GET --header 'Accept: text/plain' 'https://staging-api.revelator.com/royaltyTokens/12345'
Response
{
  "royaltyTokenId": 0,
  "royaltyTokenAddress": "string",
  "enterpriseId": 0,
  "createdBy": "00000000-0000-0000-0000-000000000000",
  "createdAt": "2024-04-04T01:52:25.649Z",
  "assetType": "track",
  "assetId": 0,
  "assetMetadataJson": "string",
  "track": {
    "name": "string",
    "isrc": "string",
    "version": "string",
    "artist": {
      "artistId": 0,
      "name": "string"
    },
    "image": {
      "fileId": "00000000-0000-0000-0000-000000000000",
      "filename": "string",
      "creationDate": "2024-04-04T01:52:25.649Z",
      "lastUpdateDate": "2024-04-04T01:52:25.649Z"
    }
  },
  "holders": [
    {
      "account": "string",
      "friendlyName": "string",
      "balance": "string",
      "isAdmin": true
    }
  ],
  "smartContractStandard": "ERC20",
  "status": "validationPending",
  "royaltyTokenURI": "string",
  "network": "string",
  "fees": "string",
  "asset": {
    "type": "string",
    "assetURI": "string",
    "ownerURI": "string",
    "artist": "string",
    "name": "string",
    "description": "string",
    "bpm": 0,
    "duration": 0,
    "key": "string",
    "genre": "string",
    "image": "string",
    "artistImageURL": "string",
    "spotifyId": "string",
    "appleId": 0,
    "trackMimeType": "string",
    "artworkMimeType": "string",
    "tags": [
      "string"
    ],
    "locationCreated": "string",
    "external_url": [
      {
        "name": "string",
        "url": "string"
      }
    ],
    "animation_url": "string",
    "youtube_url": "string",
    "originalReleaseDate": "string",
    "recordLabel": "string",
    "publisher": "string",
    "upc": "string",
    "isrc": "string",
    "lyrics": "string",
    "language": "string",
    "attributes": [
      {
        "trait_type": "string",
        "value": "string"
      }
    ],
    "credits": [
      {
        "name": "string",
        "creditType": "string"
      }
    ],
    "releases": [
      {
        "releaseType": "string",
        "releaseTitle": "string",
        "artist": "string",
        "releaseDate": "string",
        "recordLabel": "string",
        "upc": 0,
        "imageURL": "string"
      }
    ],
    "platform": {
      "name": "string",
      "imageURL": "string",
      "assetId": "string",
      "enterpriseId": "string"
    }
  }
}

Royalty Token statuses

A list of all possible statuses

Status
validationPending
validationInProgress
validationFailed
sendCreationPending
sendCreationInProgress
sendCreationFailed
checkCreationStatusPending
checkCreationStatusInProgress
checkCreationStatusFailed
contractCreationPending
contractCreationInProgress
contractCreationFailed
contractCreationCompleted