Token allowances
This guide walks through the process of setting, verifying, and utilizing token allowances for TREX tokens, with special attention to blockchain transaction signature management.
For those unfamiliar with blockchain concepts, a token allowance is a permission you give to another account (often a smart contract or application) to spend a certain amount of your tokens on your behalf. It's similar to giving someone a spending limit on your credit card—they can use your funds, but only up to the amount you've approved. This mechanism helps maintain control and security over your assets while enabling automated or delegated transactions.
For detailed parameter specifications and error codes, please refer to the Swagger documentation.
What You'll Need
- A registered and KYC-verified account
- Qualified investor status for the specific token
- A compatible wallet with sufficient funds for gas fees
- The token ID of the asset you want to interact with
Prerequisites:
To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:
- Make sure to leverage an existing account, e.g. Agent, Owner, etc.
- Sign into your Servicing portal to disable your 2FA.
- Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.
- Add the JWT to the header of your request.
Complete Token Allowance Workflow
Step 1: Determine the Allowance Type
Before setting an allowance, determine which transfer type is appropriate for your use case:
DEFAULT
: Standard allowance for TREX token transfers.DVA
(Delivery Versus Approval): Used for conditional transfers requiring prior approval.DVD
(Delivery Versus Delivery): Used for swaps between parties.
Step 2: Initiate an Allowance Request
Call the Set Allowance endpoint:
POST /v2/assets/investor/tokens/{tokenId}/allowances
Include in your request:
- Sender address (your wallet address)
- Amount of tokens to allow for spending
- Allowance type (
DEFAULT
for standard transfers)
The API will return:
- A
taskId
for tracking this operation - The unsigned transaction payload that requires your signature
Step 3: Sign and Submit the Allowance Transaction
Refer to the guide based on the specific sign and broadcast solution your API integration requires by visiting the following link: Blockchain signature flow.
Option A: Sign and Broadcast Yourself
Include the taskId
returned in the previous endpoint's response when calling the following transaction logging endpoint.
Logging the transaction is essential to reconcile on-chain and off-chain flows. Since the user handles blockchain interactions on their own, we use the taskId
to:
- Identify the workflow uniquely.
- Maintain a consistent link between offchain logic and onchain activity.
- Ensure traceability and reliability in our subscription/order system.
Steps to Complete Allowance:
- Sign the transaction payload
- Broadcast the signed transaction to the blockchain network
- Log the transaction hash:
POST /v2/assets/investor/tokens/{tokenId}/allowances/{allowanceId}/transactions
With Payload:
{
"transactionHash": "0x123..."
}
Option B: Sign and Let Our Platform Broadcast
- Sign the transaction payload
- Send the signed payload:
POST /v2/assets/investor/tokens/{tokenId}/allowances/{allowanceId}/payloads
- With Payload:
{
"signedPayloads": [
{
"id": "payload-1",
"signature": "0x..."
}
]
Step 4: Verify the Allowance
To confirm your allowance was set correctly:
- Query the API directly:
GET /v2/assets/investor/tokens/{tokenId}/allowances?senderAddress={yourAddress}
- Verify the returned allowance matches your expected values
Updated 1 day ago