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.

Wallet Qualification

For the regulatory reports Avenia sends to BACEN (Brazil's Central Bank), every wallet you send crypto to must be qualified: whether the wallet is self-custodied, who its beneficiary is, which institution holds it if it isn't self-custodied, the beneficiary's country and, for international wallets, the purpose of the transfers. The qualification fields are optional when you register a wallet, so existing integrations keep working, but you should always send them: see the warning below about defaults.

Qualification is a decision tree on isSelfCustody, which is required as soon as you send any qualification field:

`isSelfCustody`	`beneficiaryCountry`	Also required
`true`	Omitted (stored as BR) or BR	`beneficiaryName`
`true`	Any other country	`beneficiaryName`, `purposeCode`
`false`	BR	`beneficiaryName`, `custodianName`
`false`	Any other country	`beneficiaryName`, `custodianName`, `purposeCode`

beneficiaryName: the person or company that owns the funds in the wallet, up to 100 characters.
beneficiaryCountry: ISO 3166-1 alpha-2 code from Countries. Required when the wallet is not self-custodied.
custodianName: the exchange or institution that holds the wallet, such as Binance. Only for wallets that are not self-custodied; it's rejected on self-custody.
purposeCode: one of the Central Bank codes from Qualification Options; send only the code. Only for international wallets; it's rejected when the country is BR.
If you send any qualification field, the whole qualification must be valid. Otherwise the request returns 400 with a message naming the missing or invalid field.
The same walletAddress can be registered more than once (for example with different purposes); each registration needs its own alias.

Qualification status

Every wallet returns a qualificationStatus:

qualificationStatus	Meaning
`QUALIFIED`	You declared the qualification, on creation or with Qualify Beneficiary Wallet.
`DEFAULT_APPLIED`	Registered without any qualification field. Avenia applies the defaults: not self-custodied, custodian Avenia LLC, country US, purpose 67995 (transfer between accounts of the same holder) and your account holder's name as beneficiary.
`PENDING`	A wallet registered before qualification existed. Qualify it with Qualify Beneficiary Wallet.

Defaults are not a qualification

The defaults applied to DEFAULT_APPLIED wallets are only a placeholder so that registration keeps working; they may not describe the real wallet. You are responsible for the correct information: send the real qualification when you register the wallet, or update it afterwards with Qualify Beneficiary Wallet.

Create Beneficiary Wallet

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

Fields

Field	Type	Required	Description
alias	string	Yes	A custom name for the wallet to help identify it.
description	string	No	A brief description of the wallet.
walletAddress	string	Yes	The blockchain wallet address.
walletChain	string	Yes	The blockchain network of the wallet (e.g., POLYGON, CELO, ETHEREUM, GNOSIS, MOONBEAM and TRON
walletMemo	string	No	Memo for the wallet.
isSelfCustody	boolean	Conditional	Whether the beneficiary controls the wallet's keys. Required as soon as any qualification field is sent. Omit every qualification field to get the defaults. See Wallet Qualification.
beneficiaryName	string	Conditional	Name of the wallet's beneficiary, up to 100 characters. Required when qualifying.
beneficiaryCountry	string	Conditional	Beneficiary's country, ISO 3166-1 alpha-2 (e.g. US). Required when `isSelfCustody` is `false`; defaults to BR for self-custody.
custodianName	string	Conditional	Exchange or institution holding the wallet. Required when `isSelfCustody` is `false`; not allowed otherwise.
purposeCode	string	Conditional	Central Bank purpose code. Required when `beneficiaryCountry` is not BR; not allowed otherwise.

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",
  "isSelfCustody": false,
  "custodianName": "Binance",
  "beneficiaryName": "John Doe",
  "beneficiaryCountry": "US",
  "purposeCode": "46002"
}

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",
  "isSelfCustody": false,
  "custodianName": "Binance",
  "beneficiaryName": "John Doe",
  "beneficiaryCountry": "US",
  "purposeCode": "46002"
}'

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

Field	Type	Description
alias	string	Filters results to include only those with the specified alias.
walletAddress	string	Filters results to include only those with the specified wallet address.
walletChain	string	Filters results to include only those on a specific blockchain chain.
qualificationStatus	string	QUALIFIED, DEFAULT_APPLIED or PENDING. Use PENDING to find the wallets you still need to qualify.
createdAfter	int64	Unix epoch timestamp in milliseconds (UTC) — e.g. `1700000000000`. Returns results created on or after this instant (`createdAt >= createdAfter`).
createdBefore	int64	Unix epoch timestamp in milliseconds (UTC) — e.g. `1800000000000`. Returns results created strictly before this instant (`createdAt < createdBefore`).
cursor	string	Cursor 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.

Wallets to qualify

GET /v2/account/beneficiaries/wallets/?qualificationStatus=PENDING lists the Main Account wallets that still need qualification; add subAccountId to check a sub-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",
      "isSelfCustody": false,
      "custodianName": "Binance",
      "beneficiaryName": "John Doe",
      "beneficiaryCountry": "US",
      "purposeCode": "46002",
      "qualificationStatus": "QUALIFIED",
      "acamGroup": "I",
      "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",
  "isSelfCustody": false,
  "custodianName": "Avenia LLC",
  "beneficiaryName": "MARIA SILVA",
  "beneficiaryCountry": "US",
  "purposeCode": "67995",
  "qualificationStatus": "DEFAULT_APPLIED",
  "acamGroup": "I",
  "createdAt": "2025-02-20T14:13:02.065846Z"
}

Qualify Beneficiary Wallet

Qualify a PENDING or DEFAULT_APPLIED wallet, or correct the qualification of a QUALIFIED one. It takes the same fields and rules as creation, with isSelfCustody always required. The whole qualification is replaced, so any qualification field you omit is cleared, and the wallet becomes QUALIFIED.

Only qualification fields are accepted: sending alias, walletAddress, walletChain or any other field returns 400. To use a different address, register a new wallet.

info

To perform this operation for a sub-account, pass the subAccountId field as a parameter. It requires the Beneficiary or Admin permission. For accesses under multi-signature approval, the request returns 202 Accepted with an operationId, and the qualification is applied once the operation is approved and executed.

HTTP Patch Request

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

cUrl Example

curl -X PATCH "https://api.sandbox.avenia.io:10952/v2/account/beneficiaries/wallets/00000000-0000-0000-0000-000000000000" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer eyJhdXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" \
-d '{
  "isSelfCustody": true,
  "beneficiaryName": "Maria Silva"
}'

JSON Response

Returns the updated wallet. Here the country was omitted on a self-custodied wallet, so it's stored as BR:

{
  "wallet": {
    "id": "00000000-0000-0000-0000-000000000000",
    "alias": "ExampleAlias",
    "description": "Example description",
    "walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "walletChain": "POLYGON",
    "walletMemo": "memo",
    "isSelfCustody": true,
    "custodianName": "",
    "beneficiaryName": "Maria Silva",
    "beneficiaryCountry": "BR",
    "purposeCode": "",
    "qualificationStatus": "QUALIFIED",
    "acamGroup": "III",
    "createdAt": "2025-02-20T14:13:02.065846Z"
  }
}

Qualification Options

Public endpoint (no authentication) listing the Central Bank purpose codes and the defaults applied to wallets registered without qualification. Use it to build your qualification form and send only the code as purposeCode.

The purpose codes are the Central Bank's "fatos naturais" table (November 2023) plus a few codes Avenia accepted before it. Each code comes with its group and description in Portuguese (pt), English (en) and Spanish (es), so you can show them in your user's language. Always read the list from this endpoint instead of hard-coding it.

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/beneficiaries/wallets/qualification-options

JSON Response

Excerpt — the real response lists every code:

{
  "purposeCodes": [
    {
      "code": "46002",
      "group": { "pt": "Serviços diversos", "en": "Miscellaneous services", "es": "Servicios diversos" },
      "description": { "pt": "Serviços de computação e de informação", "en": "Computer and information services", "es": "Servicios de informática y de información" }
    },
    {
      "code": "67995",
      "group": { "pt": "Capitais brasileiros", "en": "Brazilian capital", "es": "Capitales brasileños" },
      "description": {
        "pt": "Transferência entre contas da mesma pessoa (natural ou jurídica)",
        "en": "Transfer between accounts of the same person (natural or legal)",
        "es": "Transferencia entre cuentas de la misma persona (física o jurídica)"
      }
    }
  ],
  "defaults": {
    "isSelfCustody": false,
    "custodianName": "Avenia LLC",
    "beneficiaryCountry": "US",
    "purposeCode": "67995",
    "acamGroup": "I"
  }
}

Countries

Public endpoint (no authentication) listing the ISO 3166-1 alpha-2 country codes the API accepts as beneficiaryCountry.

HTTP Get Request

https://api.sandbox.avenia.io:10952/v2/countries

JSON Response

{
  "countries": [
    { "code": "AD", "name": "Andorra" },
    { "code": "AE", "name": "United Arab Emirates" },
    { "code": "BR", "name": "Brazil" }
  ]
}

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.

Introduction​

Wallet Qualification​

Qualification status​

Create Beneficiary Wallet​

Fields​

HTTP Post Request​

Sample JSON Body​

cUrl Example​

JSON Response​

Get all Beneficiary Wallets​

HTTP Get Request​

URL Parameters​

cUrl Example​

JSON Response​

Get Beneficiary Wallet by ID​

HTTP Get Request​

cUrl Example​

JSON Response​

Qualify Beneficiary Wallet​

HTTP Patch Request​

cUrl Example​

JSON Response​

Qualification Options​

HTTP Get Request​

JSON Response​

Countries​

HTTP Get Request​

JSON Response​

Delete Beneficiary Wallet​

HTTP Delete Request​

cUrl Example​

Introduction

Wallet Qualification

Qualification status

Create Beneficiary Wallet

Fields

HTTP Post Request

Sample JSON Body

cUrl Example

JSON Response

Get all Beneficiary Wallets

HTTP Get Request

URL Parameters

cUrl Example

JSON Response

Get Beneficiary Wallet by ID

HTTP Get Request

cUrl Example

JSON Response

Qualify Beneficiary Wallet

HTTP Patch Request

cUrl Example

JSON Response

Qualification Options

HTTP Get Request

JSON Response

Countries

HTTP Get Request

JSON Response

Delete Beneficiary Wallet

HTTP Delete Request

cUrl Example