External wallets management
Making the most out of webhook technology to seamlessly sign transactions on Tokeny's T-REX Engine
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:
- You call the T-REX Engine Assets API to mint tokens on an investor wallet
- The T-REX Engine Assets API will answer with a HTTP201 code, indicating your transaction is being prepared
- Once the transaction payload has been validated and created, you will receive on your webhook a notification with:
- The payload to sign
- The workflowId used internally by the T-REX Engine to reconcile operations
- 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 conventionsignedMessage
is used to make sure you own the wallet for which you are subscribing. Use your wallet to sign the messagetokeny-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:
- The signature doesn't match with the provided wallet address
- Either you signed the wrong message. Make sure you sign
tokeny-notification-subscribe
- Either you signed with the wrong wallet
- Either you signed the wrong message. Make sure you sign
- There is a format issue in one of the fields you provided
- 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 providergasEstimation
is the current gas estimation for the network where the contract is deployedgasPrice
is the current gas price for the network where the contract is deployedcontractAddress
is the address where the contract is deployedblockchainNetwork
is the name of the blockchain network where the contract is deployedsignerWallet
is the wallet signing the transaction
Testing the communication between 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 notificationsignedPayload
is the result of the previous step, received from your wallet providersignerWallet
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 5 days ago