Creating and deploying a new T-REX

The T-REX Factory API allows you to deploy a T-REX easily, with no interaction with the blockchain, simply by configuring some information about your token. Follow the steps below to deploy your token:

Authentication

The first step to use the T-REX Factory is to authenticate thanks to the account that has been assigned to you by your account manager. If you don't have any account, please contact your account manager or [email protected].

To authenticate, use the following cURL snippet. Don't forget to replace with your own credentials.

curl -XPOST 'https://servicing-api-staging.tokeny.com/api/auth/signin' \
  -H 'Content-Type: application/json'
  --data '{"email":"[email protected]","password":"My-p@$$w0rd"}'

Create the T-REX

To create your T-REX, you first need to fill in the basic information of your token.

cURL request

To create a new T-REX, use the following cURL snippet:

curl -XPOST 'https://trex-factory-api-staging.tokeny.com/api/tokens' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --data-binary '{"name":"Snippet Token","symbol":"SNPTKN","decimals":6}' \
  --compressed

Parameters

name corresponds to the name you want to give to your token. It is a free string, without any special characters, length between 2 and 32 characters.
symbol is the symbol of your token on the blockchain, between 2 and 32 characters.
decimals is the number of decimals for your token, it is a plain number between 0 and 18.
owner optional, is the wallet address that will own the smart contracts. By default, ownership will be given to a Tokeny wallet, making it easier for the issuer to get help in testing.

Name and symbol can be a duplicate from an existing token that already exists on the blockchain, although we encourage you not to do so to avoid confusion, for you and your customers.

Response

The response from the previous call is formatted as follows:

{
   "decimals":6,
   "id":"<token id>",
   "name":"Snippet Token",
   "symbol":"SNPTKN"
}

You can see the parameters that you previously entered, plus the id of your token. Keep it close, it will come in handy for the next calls.

Troubleshooting

The format of error is the following:

{
    "code":"E_TOKEN_DECIMALS_NOT_INTEGER"
    "message":"Token decimals is not an integer"
}

You can receive the following HTTP error codes:

400 with code:
- E_TOKEN_NAME_NOT_ALPHANUMERIC: you have unauthorized character(s) in your token name. Make sure you are not introducing any special character in it.
- E_TOKEN_SYMBOL_NOT_ALPHANUMBERIC: you have unauthorized character(s) in your token symbol (ticker). Make you are not introducing any special character in it.
- E_TOKEN_DECIMALS_NEGATIVE: you have input a negative number of decimals which is not allowed
- E_TOKEN_DECIMALS_TOO_HIGH: you have input a number of decimals which exceeds the limit of 18
- E_TOKEN_DECIMALS_NOT_INTEGER : you have input a non-numeric number of decimals
- E_TOKEN_NAME_TOO_LONG: The length of the name of the token exceeds the maximum limit of 32 characters
- E_TOKEN_SYMBOL_TOO_SHORT: The length of the symbol of the token is too short (minimum is 2 characters)
- E_TOKEN_SYMBOL_TOO_LONG: The length of the symbol of the token exceeds the maximum limit of 32 characters
401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website. .
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Get your T-REX information

At any point along the way, you may need to get the current configuration of your token. To do so, call the following endpoint.

cURL

curl -XGET 'https://trex-factory-api-staging.tokeny.com/api/tokens/<token_id>' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --compressed

Parameters

token_id is the id of the token when you created it at the first step.
jwt is the authentication token you got from the authentication endpoint.

Result

{
   "complianceSmartContractAddress":null,
   "decimals":6,
   "deploymentStatus":"NOT_DEPLOYED",
   "id":"ae00ed2b-008c-400f-bcba-b71d9a0e5bfe",
   "identityRegistryStorageSmartContractAddress":null,
   "initialPositionReport":{
      "holders":[
         
      ],
      "uploadDate":"1970-01-01T00:00:00.000Z"
   },
   "logoURL":null,
   "name":"Snippet Token",
   "requiredClaimTypes":[
      
   ],
   "securityID":null,
   "symbol":"SNPTKN",
   "tokenAddress":null
}

complianceSmartContractAddress is the address of the compliance smart contract linked to your token. It has not been filled out yet, so it will be null at this stage, and will contain a valid ethereum address afterwards. For more information on compliance smart contracts, see the following page.
decimals is the number of decimals for your T-REX, as defined in the first step.
deploymentStatus is the status of the deployment of your T-REX. It can have three values
- NOT_DEPLOYED: Your T-REX is not deployed and all information are locally saved in the T-REX Factory API
- IN_PROGRESS: You have triggered the deployment of your T-REX and it is pending completion
- DEPLOYED: Your T-REX has been successfully deployed on the blockchain.
id: The id of your token
identityRegistryStorageSmartContractAdress: the identity storage smart contract linked to your token. As it has not been set yet, it will be null at this stage, and contain a valid ethereum address afterwards. For more information of identity storage smart contracts, see the following page.
initialPositionReport: The list of holders for the token if it represents an existing offering. This is not mandatory
- 'holders`: A list of holders information (see Whitelisting for more information)
- uploadDate: The date and time of the upload of the file.
- logoURL: The URL pointing to the logo of the token.
name: The name of the token, as defined on the 1st step
requiredClaimTypes: The claim required on the ONCHAINID to receive that T-REX. More information on next step.
securityID: The onchain identifier of the token. More on this feature in the coming months.
symbol: The symbol of the token as defined on the 1st step.
tokenAddress: The address of the T-REX Smart Contract on the blockchain.

Troubleshooting

The format of the error is the following:

{
    "code":"E_UNAUTHORIZED"
    "message":"Authentication is wrong"
}

401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Required claim configuration

One of the core component of the T-REX validation is the issuance of a claim by a trusted third-party on the investor's ONCHAINID. On this step, you will chose the trusted claim issuer which will be responsible for the issuance of the required claim for this T-REX.
There are three endpoints to call for this step:

Get the trusted claim issuers from your account
Get the claim types available
Defined the required claim for your T-REX

Get the trusted claim issuers

First, you need to retrieve the list of the trusted claim issuers linked to your account.

cURL

curl -XGET 'https://trex-factory-api-staging.tokeny.com/api/claim-issuers' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --compressed

Parameters

jwt: The jwt authorization token that you retrieved on the authentication step.

Response

{
   "count":1,
   "claimIssuers":[
      {
         "name":"Tokeny",
         "onchainID":"0xf2fb37491Ab608B468e0DCA1A1a66348bB2f64aE",
         "emissibleClaimTypes":[
            {
               "description":"Specific KYC Status",
               "name":"SPECIFIC_KYC_STATUS",
               "topic":"10101010000114"
            }
         ]
      }
   ]
}

count: The number of claim issuers in your account
claimIssuers: The list of claim issuers linked to your account
- name: The name of the claim issuer
- onchainid: The ONCHAINID of the claim issuer
- emissibleClaimTypes: The list of claim types the claim issuer is able to emit
  - description: The description of the claim type
  - name: The name of the claim type
  - topic: The topic number representing the claim topic

Troubleshooting

The format of the error is the following:

{
   "code":"E_UNAUTHORIZED"
   "message":"Authentication is wrong"
}

401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Get the claim types

Second, you need to retrieve the list of claim types you can define for your required claim.

cURL

curl -XGET 'https://trex-factory-api-staging.tokeny.com/api/claim-types' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --compressed

Parameters

jwt: The jwt authorization token that you retrieved on the authentication step.

Response

{
   "count":1,
   "claimTypes":[
      {
         "description":"Specific KYC Status",
         "name":"SPECIFIC_KYC_STATUS",
         "topic":"10101010000114"
      }
   ]
}

count: The number of available claim types
claimTypes: The available claim types
- description: The description of the claim type
- name: The name of the claim type
- topic: The topic number representing the claim topic

Troubleshooting

The format of the error is the following:

{
   "code":"E_UNAUTHORIZED"
   "message":"Authentication is wrong"
}

401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Define the required claim for the T-REX

In this last action, you will combine both results from the two previous actions to define the required claim for your action and who you trust to issue it.

Chose the claim type

cURL

curl -XPOST 'https://trex-factory-api-staging.tokeny.com/api/tokens/<token_id>/claim-types' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --data-binary '{"topic":"<claim_topic>"}' \
  --compressed

Parameters

token_id: The identifier of the token from the token creation step
jwt: The jwt authorization token that you retrieved on the authentication step.
claim_topic: The number representing the claim topic retrieved at the previous action

Response

202 in case everything goes right

Troubleshooting

The format of the error message is the following:

{
   "code":"E_TOPIC_INVALID"
   "message":"Topic is not valid"
}

400 with code:
- E_TOPIC_INVALID: The claim topic chosen is invalid
401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
404 with code:
- E_TOKEN_NOT_FOUND: The token passed in the URL doesn't exist
- E_CLAIM_TYPE_NOT_FOUND: The claim type chosen doesn't exist
409 with code
- E_CLAIM_TYPE_ALREADY_REQUIRED: The claim you chose is already required on this token
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Chose the claim issuer

cURL request

curl -XPOST 'https://trex-factory-api-staging.tokeny.com/api/tokens/<token_id>/claim-types/<claim_topic>/claim-issuers' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --data-binary '{"claimIssuerOnchainID":"<claim_issuer_onchainid>"}' \
  --compressed

Parameters

token_id: The identifier of the token from the token creation step
jwt: The jwt authorization token that you retrieved on the authentication step.
claim_topic: The number representing the claim topic retrieved at the previous action
claim_issuer_onchainid: The ONCHAINID of the claim issuer found at the previous action

Response

202 in case everything goes right

Troubleshooting

The format of the error message is the following:

{
   "code":"E_UNAUTHORIZED"
   "message":"Authentication is wrong"
}

400 with code:
- E_CLAIM_ISSUER_NOT_GRANTED_TO_EMIT_CLAIM_TYPE: The selected claim issuer is not allowed to emit the chosen claim topic
- E_INVALID_ONCHAIN_ID: The specified ONCHAINID is not valid (either the format is wrong or it doesn't exist in our service)
- E_TOPIC_INVALID: The specified token is invalid.
401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
404 with code:
- E_TOKEN_NOT_FOUND: The token passed in the URL doesn't exist
- E_CLAIM_TYPE_NOT_FOUND: The claim type chosen doesn't exist
- E_REQUIRED_CLAIM_TYPE_NOT_FOUND: The required claim type chosen doesn't exist
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Set the compliance

In this step, you will set up the compliance you want to link to the T-REX. You have two options:

Use the default compliance smart contract: this option will let all the transfer pass through without limitation
Give the address of an existing smart contract: this option will link your T-REX to an existing compliance smart contract which was already deployed on the blockchain

cURL

curl -XPUT 'https://trex-factory-api-staging.tokeny.com/api/tokens/<token_id>/compliance' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --data-binary '{"complianceSmartContractAddress":<compliance_address>}' \
  --compressed

Parameters

token_id: The identifier of the token from the token creation step
jwt: The authorization token from the authentication step
compliance_address: The address of the compliance smart contract which has been previously deployed, or if you want to use the default compliance smart contract you should use "customComplianceType":"None"

Response

200 if everything went well

Troubleshooting

The format of the error message is the following:

{
   "code":"E_UNAUTHORIZED"
   "message":"Authentication is wrong"
}

400 with code:
- E_ETHEREUM_ADDRESS_INVALID: The specified smart contract address is not a valid ethereum address
- E_INVALID_ONCHAIN_ID: The specified ONCHAINID is not valid (either the format is wrong or it doesn't exist in our service)
- E_TOPIC_INVALID: The specified token is invalid.
401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
404 with code:
- E_TOKEN_NOT_FOUND: The token passed in the URL doesn't exist
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Set the identity storage

This is the last step of the configuration, where you will define which option you want to use for the identity storage:

Either use a new identity storage, meaning that no investors will be shared with another token
An existing smart contract address, meaning that you can share investors with another token

cURL

curl -XPUT 'https://trex-factory-api-staging.tokeny.com/api/tokens/<token_id>/identityStorage' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --data-binary '{"identityStorageSmartContractAddress":<storage_address>}' \
  --compressed

Parameters

token_id: The identifier of the token from the token creation step
jwt: The authorization token from the authentication step
storage_address: The address of the identity storage smart contract which has been previously deployed, or null if you want to use a new identity storage smart contract

Response

200 if everything went well

Troubleshooting

The format of the error message is the following:

{
   "code":"E_UNAUTHORIZED"
   "message":"Authentication is wrong"
}

400 with code:
- E_ETHEREUM_ADDRESS_INVALID: The specified smart contract address is not a valid ethereum address
- E_INVALID_ONCHAIN_ID: The specified ONCHAINID is not valid (either the format is wrong or it doesn't exist in our service)
- E_TOPIC_INVALID: The specified token is invalid.
401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
404 with code:
- E_TOKEN_NOT_FOUND: The token passed in the URL doesn't exist
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Trigger the deployment of the T-REX

If you followed all the previous steps, you have finalized the configuration of your T-REX and it is ready to be deployed to the blockchain.

cURL

curl -XPOST 'https://trex-factory-api-staging.tokeny.com/api/tokens/<token_id>/deploy' \
  -H 'authorization: Bearer <jwt>' \
  -H 'content-type: application/json' \
  -H 'accept: */*' \
  --compressed

Parameters

token_id: The identifier of the token from the token creation step
jwt: The authorization token from the authentication step

Response

202 if everything went well

Troubleshooting

The format of the error message is the following:

{
   "code":"E_UNAUTHORIZED"
   "message":"Authentication is wrong"
}

401 with code:
- E_UNAUTHORIZED: you are not authenticated or your authentication has expired. Please authenticate again. If error persists, please open a ticket on the support website.
403 with code:
- E_REQUIRED_CLAIM_TYPE_MISS_TRUSTED_CLAIM_ISSUER: The claim issuer of the required claim type is missing. Go back to the previous steps to fix this.
- E_REQUIRED_CLAIM_TYPE_NOT_FOUND: The required claim type is missing on the T-REX configuration
- E_TOKEN_IS_ALREADY_BEING_DEPLOYED: The deployment of the T-REX has already been triggered. Refer to the next step to retrieve the deployment status of your token.
- E_TOKEN_IS_ALREADY_DEPLOYED: The deployment of the T-REX has already been completed. Refer to the next step to retrieve the deployment status of your token.
- E_TOKEN_MISS_REQUIRED_CLAIM_TYPE: The required claim type is missing from the T-REX configuration. Go back to the previous steps to fix this.
- E_TRUSTED_CLAIM_ISSUER_NOT_FOUND: The specified claim issuer cannot be found. Go back to the previous steps to fix this.
404 with code:
- E_TOKEN_NOT_FOUND: The token passed in the URL doesn't exist
500 with code
- E_INTERNAL_ERROR: An internal server error happened. Please retrieve the correlation_id from the header response and open a ticket on the support website.

Get the deployment status

Call the "Get your T-REX information" endpoint and check the deploymentStatus to know the progress of the deployment of your token.