Peer-to-Peer Transfers and Other Registrar Functions (Burn Tokens, Clawbacks, etc)

You may use our API to transfer tokenized securities directly from customer wallet to customer wallet (peer-to-peer). This function can be used to create simple secondary markets such as bulletin boards or for edge cases such as inheritances.

ℹ️ This function is for now only available for EVM tokens (Polygon) and for sender wallets that are custodied by Tangany. External wallets can receive tokenized securities via peer-to-peer transfers, but cannot send them.

The cash leg is, for the time being, not covered by this. It is only for securities tokenized with NYALA's engine.

Pre-requisites for a transfer of tokenized security

As soon as you create a new transfer request via API, our system will perform multiple automated checks. If any of the check fails, the transfer status will be "Failed". Detailed error messages will indicate the exact reason for the failure.

The following checks are performed:

• The sender must have sufficient token balance in their wallet
• The recipient must have a customer entry, a wallet and their full KYC data already saved in our database. Make sure that you have triggered the Create Customer, Save KYC data and Register Wallet endpoints before you allow the transfer in your system
• The tokens must not be frozen by the registrar

If all checks pass, our system will automatically opt-in (whitelist) the recipient's wallet and execute the transfer. This operation takes the highest priority over other operations such as token distributions from the registrar's issuer wallet.

POST Asset Transfer /api/external/v1/customers/retail-wallets/asset-transfer

Request Example:

# UAT BASE_URL: https://uat.api.nyala.de
# Production BASE_URL: https://api.nyala.de

curl -i -X POST \
  https://api.nyala.de/api/external/v1/customers/retail-wallets/asset-transfer \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "senderWalletId": "35c56557-40ae-4a50-bb58-1a3b35160b82",
      "recipientWalletId": "8c07a449-acb8-4144-bace-b1962d4cf954",
      "tokenizedAssetId": "ad18357f-6719-482f-a109-bd87822008b9",
      "amount": 0.1,
      "message": "string",
      "blockchain": "Polygon"
    }
  ]'

Response Example:

{
  "errorMessageCodes": [
    "string"
  ],
  "errors": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "senderWalletId": "35c56557-40ae-4a50-bb58-1a3b35160b82",
      "recipientWalletId": "8c07a449-acb8-4144-bace-b1962d4cf954",
      "result": "string",
      "senderOptInStatus": "string",
      "recipientOptInStatus": "string"
    }
  ],
  "warnings": [
    "string"
  ]
}

ℹ️ Don't forget to fetch new registry extracts! After the transfer is successful, do not forget to fetch updated registry extracts that reflects the Sender and the Recipient's new balances. This is done by following the same steps you would normally use to generate and download registry extracts. Use the Generate Registry Extract endpoint first to generate the new extract. Refer to the registry extract article.

To get a list of past transfers for a given customer, use the transfer status endpoint:

GET Asset Transfer Status /api/external/v1/customers/retail-wallets/asset-transfer/{transfer-id}/status

Request Example:

curl -i -X GET \
  'https://api.nyala.de/api/external/v1/customers/retail-wallets/asset-transfer/{transfer-id}/status'

Response Example:

{
  "errorMessageCodes": [
    "string"
  ],
  "errors": [
    {
      "code": "string",
      "message": "string",
      "field": "string"
    }
  ],
  "data": {
    "tokenizedAssetId": "ad18357f-6719-482f-a109-bd87822008b9",
    "senderWalletId": "35c56557-40ae-4a50-bb58-1a3b35160b82",
    "senderAddress": "string",
    "recipientAddress": "string",
    "recipientWalletId": "8c07a449-acb8-4144-bace-b1962d4cf954",
    "amount": 0.1,
    "message": "string",
    "status": "string",
    "created": "2019-08-24T14:15:22Z",
    "blockchainTxId": "string"
  },
  "warnings": [
    "string"
  ]
}

NYALA's registrar subsidiary Smart Registry GmbH is an entity regulated by the German financial regulator BaFin. This means that there are several functions that the registrar must possess with regards to the tokenized securities we register. We use the ERC-3643 (formerly known as T-REX) standard which is the most recognized open-source suite of smart contracts that enables the issuance, management, and transfer of permissioned tokens.

Such functions are not available to external clients. Nonetheless, they are a crucial part of ensuring that securities laws such as the German eWpG are being followed.

The registrar keeps the sole rights to the following token operations. These operations are available to the registrar regardless of which wallet they are contained in, since they happen at the token level – meaning the issuer wallet can control the ERC-3643 tokens wherever they end up.

These functions are not available for you to trigger via external API endpoints. Should you need us to execute them, however, you can provide us the request with the appropriate justification at any time, and we will take care of it for you. Examples of said requests can include inheritance cases or watchlist flags detected after initial token distribution

For more specific cases where the total supply of tokens must be periodically reduced, for example when redemptions against an underlying should be made possible (which would require burning tokens) we can set up a dedicated endpoint for you after formal contractual agreement.