DocumentationAPI Endpoints
Documentation
Tokeny.com

External wallets management

Making the most out of webhook technology to seamlessly sign transactions on Tokeny's T-REX Engine

Suggest Edits

General concepts

Signing transactions

In the world of blockchain transactions, you need a wallet to sign a transaction payload before it can be integrated into the network.

T-REX Engine APIs allow you to easily prepare those transactions by interacting with the ERC-3643 Smart Contract before sending you the payload to be signed.

This is only for agents and owners accounts, not for investors.

Webhooks

Webhook technology is an event-driven mechanism that allows a system to send real-time notifications to another system.

Let's take a simple example and break it down:

  1. You call the T-REX Engine Assets API to mint tokens on an investor wallet
  2. The T-REX Engine Assets API will answer with a HTTP201 code, indicating your transaction is being prepared
  3. Once the transaction payload has been validated and created, you will receive on your webhook a notification with:
    1. The payload to sign
    2. The workflowId used internally by the T-REX Engine to reconcile operations
  4. You broadcast the transaction using T-REX Engine Broadcast Endpoint

Wallet support

T-REX Engine doesn't integrate any connectivity to wallet providers, but instead makes the choice of making the signature easy to perform, by sending directly to any ERC-20 compatible wallet provider the payload of the transaction to sign.

This way, you're not bound by Tokeny's integration, you can use the wallet provider that is the most suitable for your use case and wait for our transaction to sign notifications.

Subscription logic

The following paragraph explains the logic of how permissions are managed:

  • One API key can only have one subscription per wallet, meaning that all notifications for the wallet will be sent to one single endpoint
  • One API key can subscribe to several wallets, as long as the API key is linked to the wallet with any permission (investor, agent, owner)
  • Several API keys can subscribe to the same wallet address, as long as the API keys are linked to the wallet with any permission (investor, agent, owner)

How to integrate

Authentication

All of the endpoints

Subscribe to the relevant events

In order to receive notifications for the signature of a transaction, you need first to subscribe to them, letting T-REX Engine API know which endpoint to notify.

To simplify the integration, you subscribe to receive notifications for a specific wallet address. This means that if your wallet is used for being agent - or investor - on several tokens, you will directly receive the transaction notifications without having to perform any other set up.

To secure the endpoint, we rely on the business logic of permissions the wallet is linked to. In order to be able to subscribe to notifications, you need to be one of - or a combination of:

  • Investor: you have been qualified with this wallet address on one or several token(s).
  • Agent / issuer: you have one - or more - agent account(s) linked to this wallet address.
  • Owner: you have one - or more - owner account(s) linked to this wallet address.

Create a new subscription for a wallet address

Endpoint

To subscribe to transaction notifications, use the following endpoint:

POST api.tokeny.com/blockchain/subscribe

Body of the request

The body of the request must have the following format:

{
  "walletAddress": "string",
  "signedMessage": "string",
  "endpoint": "string"
}

Please find below the explanation for each fields:

  • walletAddress is the address of the wallet for which your are subscribing. It must follow the ERC20 convention
  • signedMessage is used to make sure you own the wallet for which you are subscribing. Use your wallet to sign the message tokeny-notification-subscribe and send the result as part of the endpoint. We will internally make sure the signature matches the wallet provided.
  • endpoint is the endpoint you will use to receive the payload to sign (see below). Simply input the URL.

Response of the request

In case everything went well, you will receive an HTTP 201 response code.

Possible errors and troubleshooting

Unauthorized

If the wallet used is not linked to any account or without the proper permission scheme, you will receive an HTTP 401 error code. Check your wallet address and your account.

If the issue persists, please contact [email protected]

Bad request

You can receive an HTTP 400 for three reasons:

  1. The signature doesn't match with the provided wallet address
    1. Either you signed the wrong message. Make sure you sign tokeny-notification-subscribe
    2. Either you signed with the wrong wallet
  2. There is a format issue in one of the fields you provided
  3. The endpoint you provided is already used for this wallet on this API key.

Check the format and content of all of the fields and retry signing the message.

If the issue persists, please contact [email protected]

Updating the subscription with a new endpoint

As your API key can only have one subscription per wallet, you can update at any moment the endpoint to receive new notifications at any time by calling the same endpoint as above.

Implement the endpoint receiving the payload

For each transaction, you will receive an HTTP POST request on the URL given previously with the following signature:

{
  
  "tasks":
  [
    {
      "taskId": "string",
      "transactionData": "string",
      "gasEstimation": "string",
      "gasPrice": "string", 
      "contractAddress": "string",
      "blockchainNetwork": "string",
    }
  ],
  signerWallet: "string"
}

Please find below the explanation for each fields:

  • taskId is an internal identifier used by T-REX Engine to reconcile outside operations with internal ones. Note it down, it will be used in the 'Emit signed payload' step below.
  • transactionData is the payload of the transaction to be signed. It is this string that you will pass to the signing capabilities of your wallet provider
  • gasEstimation is the current gas estimation for the network where the contract is deployed
  • gasPrice is the current gas price for the network where the contract is deployed
  • contractAddress is the address where the contract is deployed
  • blockchainNetwork is the name of the blockchain network where the contract is deployed
  • signerWallet is the wallet signing the transaction

Testing the communication between the T-REX Engine Blockchain API and your implementation

In order to test the communication between the T-REX Engine and your implementation, you can simply call the following endpoint:

GET api.tokeny.com/blockchain/subscribe/:wallet-address/test

Where wallet-address is a wallet coherent with your API key.

If everything works well, you will receive the following test notification on the endpoint provided with your subscription:

{
  
  "tasks":
  [
    {
      "taskId": "66d81a1c-b024-4d4b-adbd-ed4ca647f16f",
      "transactionData": "0x123456",
      "gasEstimation": "0.2",
      "gasPrice": "0.2", 
      "contractAddress": "0xd07379a755A8f11B57610154861D694b2A0f615a",
      "blockchainNetwork": "BASE",
    }
  ],
  signerWallet: "0xFBF78D51eEb257F77a7345ED7F06c00e9E90ea8E"
}

In case no subscription exists for the provided wallet address or with your API key, you will receive an HTTP 401 error.

Sign the transaction

Once you have received the notification, you can simply call your wallet provider to sign the transactionData received in the previous step.

Please refer to the documentation of your preferred wallet provider to perform this step.

Broadcast signed payload

Endpoint

Once you have successfully signed the payload with your wallet provider, you can call the following endpoint to emit the transaction:

POST api.tokeny.com/blockchain/broadcast

Body of the request

{
  "tasks":
  [
    {
      "taskId": "string",
      "signedPayload": "string"
    }
  ],
  "signerWallet": "string"
}

You can find below the explanation of the body:

  • taskId is the identifier of the task received in the notification
  • signedPayload is the result of the previous step, received from your wallet provider
  • signerWallet is the wallet used to sign the payload

Possible errors and troubleshooting

Bad request

You can receive an HTTP 400 in the following cases:

  • One of the field above is missing
  • One of the field is badly formed

Check the content of the body and retry.

If the problem persists, please reach out to [email protected]

Unauthorized

You can receive an HTTP 401 in the following cases:

  • Your API key doesn't have any current subscription
  • The wallet used to sign is not allowed to perform the action you're trying to broadcast

Check the API key and the wallet used to sign.

If the problem persists, please reach out to [email protected]

Updated 17 days ago