DocumentationAPI Endpoints
Documentation
Tokeny.com

Token allowances

Suggest Edits

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 from the correct role, e.g. Agent, Owner, Investor, etc.
  • If this use case requires you to leverage an Agent account, make sure your 2FA is disabled via the Servicing portal.
  • 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:

  1. Sign the transaction payload
  2. Broadcast the signed transaction to the blockchain network
  3. 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

  1. Sign the transaction payload
  2. Send the signed payload:

POST /v2/assets/investor/tokens/{tokenId}/allowances/{allowanceId}/payloads

  1. With Payload:
{  
  "signedPayloads": [  
    {  
      "id": "payload-1",  
      "signature": "0x..."  
    }  
  ]

Step 4: Verify the Allowance

To confirm your allowance was set correctly:

  1. Query the API directly:

GET /v2/assets/investor/tokens/{tokenId}/allowances?senderAddress={yourAddress}

  1. Verify the returned allowance matches your expected values

Updated 17 days ago