Agent: Manage Token actions
This document outlines the list of token actions, which could be both single and batch processing, except pause, unpause and deploy. For users with appropriate plan access, a companion document details the SaaS interface for these operations and for detailed parameter specifications and error codes, please refer to the Swagger documentation.
Behavior Based on Wallet Provider Type
Any API endpoint that implies signature of a blockchain transaction will return the transaction data (payload) to be signed. Token actions behave differently based on the wallet provider type, the integrator will have two options:
- User managed wallets (e.g., MetaMask): The API Integrator sign and emit transaction, only then logs the txHash in our system with
POST /v2/assets/servicing/tokens/{tokenId}/actions/transactions
endpoint. - External custodian or Integrated wallet : The API integrator still signs, but sends the signed payload to be emitted onchain by Tokeny with
POST /v2/assets/servicing/tokens/{tokenId}/actions/payloads
endpoint.
List of token actions:
Action | Method | Endpoint |
---|---|---|
Mint | POST | /assets/servicing/tokens/{tokenId}/actions/mint |
Burn | POST | /assets/servicing/tokens/{tokenId}/actions/burn |
Block wallets | POST | /assets/servicing/tokens/{tokenId}/actions/block-wallets |
Unblock wallets | POST | /assets/servicing/tokens/{tokenId}/actions/unblock-wallets |
Block | POST | /assets/servicing/tokens/{tokenId}/actions/block |
Unblock | POST | /assets/servicing/tokens/{tokenId}/actions/unblock |
Force transfer | POST | /assets/servicing/tokens/{tokenId}/actions/force-transfer |
Pause | POST | /assets/servicing/tokens/{tokenId}/actions/pause |
Unpause | POST | /assets/servicing/tokens/{tokenId}/actions/unpause |
Deploy | POST | /assets/servicing/tokens/{tokenId}/actions/deploy |
Endpoints to sign and emit transaction data:
Operation | Method | Path |
---|---|---|
Sign and emit transaction | POST | /assets/servicing/tokens/{tokenId}/actions/{actionId}/transactions |
Only sign and send signed payload to be emitted by Tokeny | POST | /assets/servicing/tokens/{tokenId}/actions/{actionId}/payloads |
Operation | Method | Path |
---|---|---|
Sign and emit transaction | POST | /assets/servicing/tokens/{tokenId}/actions/{actionId}/transactions |
Only sign and send signed payload to be emitted by Tokeny | POST | /assets/servicing/tokens/{tokenId}/actions/{actionId}/payloads |
Step-by-Step Token Action Workflow
The following procedure applies to minting and all other token actions.
Step 1: Get all TokenHolder(s) from a token
GET /v2/assets/servicing/tokens/{tokenId}/holders
Step 2: Initiate the Action
Call the appropriate token action endpoint. The response will include the transaction payloads that need to be signed.
POST /v2/assets/servicing/tokens/{tokenId}/actions/mint
Step 3: Sign and Submit the Action 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.
You can only complete transfers that you have initiated. Additionally, include the taskId
returned in the previous endpoint's response when calling the 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 off-chain logic and on-chain activity.
- Ensure traceability and reliability.
Option A: Sign and Broadcast Yourself
- Sign the transaction payload
- Broadcast the signed transaction to the blockchain network
- Log the transaction hash:
POST /v2/assets/servicing/tokens/{tokenId}/actions/{actionId}/transactions
Option B: Sign and Let Tokeny Broadcast
- Sign the transaction payload
- Send the signed payload:
POST /v2/assets/servicing/tokens/{tokenId}/actions/{actionId}/payloads
Available Token Actions
Mint Tokens to Wallets
Create new tokens and assign them to specified wallet addresses.
POST /v2/assets/servicing/tokens/{tokenId}/actions/mint
Use Cases:
- Initial token distribution to investors
- Rewarding stakeholders with additional tokens
- Increasing token supply for specific wallets
Key Considerations:
- Only token agents can mint tokens
- Recipients must be qualified holders for the token
- For registered wallets, you'll need to sign and broadcast the transaction
Block Tokens from Wallets
Prevent specific amounts of tokens in wallets from being transferred or used.
POST /v2/assets/servicing/tokens/{tokenId}/actions/block
Use Cases:
- Regulatory compliance (freezing suspicious activity)
- Dispute resolution
- Preventing transfers during investigations
- Lock-up period enforcement
Important: Blocked tokens remain in the wallet but cannot be transferred until unblocked.
Unblock Tokens from Wallets
Remove blocking restrictions from previously blocked tokens.
POST /v2/assets/servicing/tokens/{tokenId}/actions/unblock
Use Cases:
- Resolving compliance issues
- Ending lock-up periods
- Restoring normal token functionality after investigations
Force Transfer Tokens
Move tokens between wallets without compliance restrictions.
POST /v2/assets/servicing/tokens/{tokenId}/actions/force-transfer
Use Cases:
- Regulatory enforcement actions
- Court-ordered asset transfers
- Emergency token recovery
- Correcting distribution errors
Important: Force transfers bypass all compliance rules and should be used carefully.
Burn Tokens from Wallets
Permanently destroy tokens, reducing the total supply.
POST /v2/assets/servicing/tokens/{tokenId}/actions/burn
Use Cases:
- Reducing token supply
- Removing tokens from non-compliant holders
- Token buyback programs
- Correcting over-issuance
Note: Burned tokens cannot be recovered.
Block Wallets
Prevent entire wallets from performing any token operations.
POST /v2/assets/servicing/tokens/{tokenId}/actions/block-wallets
Use Cases:
- Sanctioned addresses
- Compromised wallet security
- Regulatory compliance
- Preventing unauthorized access
Effect: Blocked wallets cannot send, receive, or interact with the token in any way.
Unblock Wallets
Restore full functionality to previously blocked wallets.
POST /v2/assets/servicing/tokens/{tokenId}/actions/unblock-wallets
Use Cases:
- Resolving security issues
- Lifting regulatory restrictions
- Restoring access after compliance verification
Deploy Token
Initiate the token deployment process to the blockchain network.
POST /v2/assets/servicing/tokens/{tokenId}/actions/deploy
Use Cases:
- Initial token launch to blockchain
- Moving from development to production environment
- Creating the on-chain token contract
Key Considerations:
- Only the token issuer can initiate deployment
- Required before any other token operations can be performed on-chain
- No signing and broadcasting required for this action
Important: This action establishes the token's existence on the blockchain and must be completed before other token actions can be executed.
Updated 1 day ago