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.
Your customers will keep all the tokens they buy through you in that one wallet.
ℹ️ Currently, we do not support multiple wallets for the same customer.
If your selected custodian is Tangany or HADC:
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 "3"
- "HADC" or "1"
ℹ️ Important information about custodian Tangany: If you selected Tangany as a custodian, please note that they only accept residents of the European Union, Iceland, Norway, Switzerland, the United Kingdom and Japan.
HADC, a German bank part of the ABN AMRO Group, accepts all residents except countries under international sanctions lists.
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.
For HADC: Approval requires a manual review by their compliance team. Please allow 5–7 business days for this process.
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
}
}