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:

ActionMethodEndpoint
MintPOST/assets/servicing/tokens/{tokenId}/actions/mint
BurnPOST/assets/servicing/tokens/{tokenId}/actions/burn
Block walletsPOST/assets/servicing/tokens/{tokenId}/actions/block-wallets
Unblock walletsPOST/assets/servicing/tokens/{tokenId}/actions/unblock-wallets
BlockPOST/assets/servicing/tokens/{tokenId}/actions/block
UnblockPOST/assets/servicing/tokens/{tokenId}/actions/unblock
Force transferPOST/assets/servicing/tokens/{tokenId}/actions/force-transfer
PausePOST/assets/servicing/tokens/{tokenId}/actions/pause
UnpausePOST/assets/servicing/tokens/{tokenId}/actions/unpause
DeployPOST/assets/servicing/tokens/{tokenId}/actions/deploy

 Endpoints to sign and emit transaction data:

OperationMethodPath
Sign and emit transactionPOST/assets/servicing/tokens/{tokenId}/actions/{actionId}/transactions
Only sign and send signed payload to be emitted by TokenyPOST/assets/servicing/tokens/{tokenId}/actions/{actionId}/payloads
OperationMethodPath
Sign and emit transactionPOST/assets/servicing/tokens/{tokenId}/actions/{actionId}/transactions
Only sign and send signed payload to be emitted by TokenyPOST/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

  1. Sign the transaction payload
  2. Broadcast the signed transaction to the blockchain network
  3. Log the transaction hash:

POST /v2/assets/servicing/tokens/{tokenId}/actions/{actionId}/transactions

Option B: Sign and Let Tokeny Broadcast

  1. Sign the transaction payload
  2. 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.