Skip to main content

Wallets

Introduction​

Beneficiary Wallets are wallets that are outside the Avenia API ecosystem. You can register any external wallet here for future operations on your business account or sub-account, if applicable.

Create Beneficiary Wallet​

Registering a new beneficiary wallet is straightforward. Let’s look at the required fields:

Fields​

FieldTypeRequiredDescription
aliasstringYesA custom name for the wallet to help identify it.
descriptionstringNoA brief description of the wallet.
walletAddressstringYesThe blockchain wallet address.
walletChainstringYesThe blockchain network of the wallet (e.g., POLYGON, CELO, ETHEREUM, GNOSIS, MOONBEAM and TRON
walletMemostringNoMemo for the wallet.
info

To perform this operation for a sub-account, pass the subAccountId field as a parameter to this endpoint.

HTTP Post Request​

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/

Sample JSON Body​

{
  "alias": "ExampleAlias",
  "description": "Example description",
  "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "walletChain": "POLYGON",
  "walletMemo": "memooo"
}

cUrl Example​

curl -X POST "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "alias": "ExampleAlias",
  "description": "Example description",
  "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "walletChain": "POLYGON",
  "walletMemo": "memooo"
}'

JSON Response​

{
  "id": "76971925-a1ca-423f-badf-0b3f2b03c51c"
}

Get all Beneficiary Wallets​

Retrieve a list of all registered beneficiary wallets using filters and pagination.

HTTP Get Request​

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/

URL Parameters​

FieldTypeDescription
aliasstringFilters results to include only those with the specified alias.
walletAddressstringFilters results to include only those with the specified wallet address.
walletChainstringFilters results to include only those on a specific blockchain chain.
createdAfterint64Unix epoch timestamp in milliseconds (UTC) — e.g. 1700000000000. Returns results created on or after this instant (created_at >= createdAfter).
createdBeforeint64Unix epoch timestamp in milliseconds (UTC) — e.g. 1800000000000. Returns results created strictly before this instant (created_at < createdBefore).
cursorstringCursor for pagination. Pass the value from the previous response to retrieve the next set of results.
info

To fetch wallets for a specific subAccount, pass the subAccountId field as an endpoint parameter. If you don’t pass it, it will fetch from your Main Account.

Timestamp format

createdAfter / createdBefore are Unix epoch timestamps in milliseconds, UTC (13 digits for current dates, e.g. 1700000000000) — not seconds. If you have a value in seconds, multiply it by 1000. The lower bound is inclusive and the upper bound is exclusive, and the returned createdAt is an RFC3339 UTC string ending in Z. Convert local date boundaries to UTC before computing the epoch.

cUrl Example​

curl -X GET "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/?alias=ExampleAlias&walletAddress=0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&walletChain=POLYGON&createdAfter=1700000000000&createdBefore=1800000000000&cursor=NEXT_CURSOR" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response​

{
  "wallets": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "alias": "ExampleAlias",
      "description": "Example description",
      "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
      "walletChain": "POLYGON",
      "walletMemo": "memo",
      "createdAt": "2025-02-20T14:13:02.065846Z"
    }
  ],
  "cursor": "MjAtMTc0MDA2MDc4MjA2NQ..."
}

Get Beneficiary Wallet by ID​

Retrieve the details of a specific beneficiary wallet:

HTTP Get Request​

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/{YOUR_UUID_ID}

cUrl Example​

curl -X GET \
  "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/{YOUR_UUID_ID}" \
  -H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

JSON Response​

{
  "id": "00000000-0000-0000-0000-000000000000",
  "alias": "ExampleAlias",
  "description": "Example description",
  "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
  "walletChain": "POLYGON",
  "walletMemo": "memo",
  "createdAt": "2025-02-20T14:13:02.065846Z"
}

Delete Beneficiary Wallet​

Delete a specific beneficiary wallet:

HTTP Delete Request​

https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/{YOUR_UUID_ID}

cUrl Example​

curl -X DELETE "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/00000000-0000-0000-0000-000000000000" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"

Your wallet has been permanently removed from the system.