For customers that come to you without an existing crypto wallet, you must initiate a wallet creation request after the customer record is created in our system.
If your customers bring / connect their own wallets (e.g. MetaMask wallets, etc.), we will classify them as "External Wallets". We will explain how to register these in our system in the last section of this page. (Keep in mind that an external wallet will be subject to some of our third party providers KYT checks, these may affect the end user experience depending on aspects like the wallets longevity or exposure to other wallets deemded as risky by KYT compliance standards.)
Your customers will keep all the tokens they buy through you in that one wallet.
ℹ️ Currently, we do not support multiple custodial wallets at Tangany for the same customer.
If you have selected Tangany as the custodian:
Send a wallet creation request using POST Initiate retail wallet: /api/external/v1/customers/{customerId}/retail-wallets
This request requires the custody_provider parameter, which accepts one of the following values:
- "Tangany" or 1
ℹ️ Important information about custodian Tangany: If you selected Tangany as the custodian, please note that they only accept residents of the European Union, Iceland, Norway, Switzerland, the United Kingdom, Ukraine and Japan.
The wallet is created on the Polygon blockchain by default. If a different blockchain is required for your operations, contact your Technical Solutions Engineer prior to integration.
ℹ️ If you choose to go with custodial wallets, you will never need to directly interact with the custodian. Every interaction will go through the NYALA API. The custodian is also not involved during the creation of the token.
Request Example:
# UAT BASE_URL: https://uat.api.nyala.de
# Production BASE_URL: https://api.nyala.de
# The {customerId} is 42557ea2-8a55-4599-85b2-2a91f343a08b
curl -X GET {{BASE_URL}}/api/external/v1/customers/42557ea2-8a55-4599-85b2-2a91f343a08b/retail-wallets \
-H "Content-Type: application/json" \
-H "Authorization: HMAC YOUR_API_KEY:GENERATED_SIGNATURE" \
-H "Content-Length: CALCULATED_CONTENT_LENGTH" \
-d '{
"custodyProvider": 1
}'Response Example:
{
"errorMessageCodes": null,
"errors": null,
"data": [
{
"id": "32d66779-5168-4a32-a0c0-24b42c299832",
"accountId": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"blockchain": 14,
"type": 2,
"status": 3,
"publicAddress": null,
"balance": {
"nativeBalance": { "free": 0.0, "locked": 0.0 },
"nativeFreeDecimalBalanceString": "0.0",
"nativeLockedDecimalBalanceString": "0.0"
},
"created": "2026-01-28T14:36:55Z"
}
]
}Your request is then processed by your chosen custody provider.
For Tangany: Approval is automated and typically takes a few seconds, provided the customer's KYC data is compliant.
Once the wallet request is approved, retrieve the customer's public address using the function GET Retail wallet details: /api/external/v1/customers/{customerId}/retail-wallets
Request Example:
# UAT BASE_URL: https://uat.api.nyala.de
# Production BASE_URL: https://api.nyala.de
# The {customerId} is 42557ea2-8a55-4599-85b2-2a91f343a08b
curl -X GET {{BASE_URL}}/api/external/v1/customers/42557ea2-8a55-4599-85b2-2a91f343a08b/retail-wallets \
-H "Content-Type: application/json" \
-H "Authorization: HMAC YOUR_API_KEY:GENERATED_SIGNATURE" \
-H "Content-Length: 0"Response Example:
{
"errorMessageCodes": null,
"errors": null,
"data": [
{
"id": "7b70d82e-f1f3-41cd-848a-22fa118f0854",
"accountId": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"publicAddress": "0x72353d150140014EC2e88c6f281c06964589e121",
"blockchain": 14,
"type": 1,
"status": 1,
"isTangany": true,
"balance": {
"nativeBalance": {
"free": 0.0,
"locked": 0.0
},
"nativeFreeDecimalBalanceString": "0.0",
"nativeLockedDecimalBalanceString": "0.0",
"nonNativeBalances": {},
"nonNativeBalancesString": {}
},
"seedLockStatus": false,
"retailWalletSeedId": "00000000-0000-0000-0000-000000000000",
"created": "2026-02-04T07:45:09.0768934Z",
"transfers": null
}
]
}You can then search for this public address on a blockchain explorer (e.g. Polygonscan) to verify token balances and transactions.
If you use external wallets (i.e. your customers bring their own wallets or open wallets through you, not through us):
The custody provider field can be left blank or set to "0".
Import the external wallet into NYALA's system using:
POST Create external wallet /api/external/v1/retail-wallets/external
You must specify the blockchain type (e.g., 14 for Polygon) and provide the existing public wallet address.
Request Example:
# UAT BASE_URL: https://uat.api.nyala.de
# Production BASE_URL: https://api.nyala.de
# The {customerId} is 42557ea2-8a55-4599-85b2-2a91f343a08b
curl -X POST {{BASE_URL}}/api/external/v1/retail-wallets/external \
-H "Content-Type: application/json" \
-H "Authorization: HMAC YOUR_API_KEY:GENERATED_SIGNATURE" \
-H "Content-Length: CALCULATED_CONTENT_LENGTH" \
-d '{
"AccountId": "42557ea2-8a55-4599-85b2-2a91f343a08b",
"Blockchain": 14,
"PublicAddress": "0x72353d150140014EC2e88c6f281c06964589e121",
"Name": "External Wallet"
}'| Parameter Name | Description | Expected Values |
|---|---|---|
| blockchain | Stating on which blockchain the wallet exists. If you send "NotSet", it will default to the same blockchain you created the tokens on. You may always send value "NotSet". | "NotSet", "Polygon", "PEAQ", "Stellar" |
| publicAddress | Public address of the wallet. | Example: "0x1234567890abcdef1234567890abcdef12345678" |
| accountID | This is the NYALA customer ID you received at Customer creation | UUID from customer creation |
| name | An optional name for the wallet. It can be left blank. |
Response Example:
{
"errorMessageCodes": null,
"errors": null,
"data": {
"id": "5ce576ef-ef6d-4d5b-b165-511e2a72fe7c",
"externalId": null
}
}| Case | Error code | Example response |
|---|---|---|
| Invalid customer ID | 500 | "title": "An error occurred while processing your request.","status": 500 |
| Duplicate request | 400 | "errorMessageCodes":["DuplicateRetailWalletRequestEntity"],"errors": null,"data": null |