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.

Wallet Qualification​

The Brazilian Central Bank requires Avenia to know who each beneficiary wallet belongs to, who holds its keys and in which country: the wallet's qualification. Avenia reports it with every on-chain payout to the wallet, and its country decides whether the payout is international:

  • a wallet whose counterpartyCountry is BR receives domestic payouts: their quote takes no purpose code;
  • any other wallet, including one with no country declared yet, receives international payouts: their quote takes an outputPurposeCode (see Purpose Code on the Quote).

See International Transfers (ACAM) for the whole flow. Wallets that send you deposits are qualified separately, as deposit sender wallets.

Optional through November 14, 2026, required from November 15, 2026

Through November 14, 2026 you may register a wallet with no qualification, or an incomplete one: it is PENDING.

From November 15, 2026:

  • a complete qualification is required to register a beneficiary wallet or to qualify one: an incomplete one returns 400 Bad Request naming the first missing field;
  • an on-chain payout only goes to a QUALIFIED wallet, in Brazil too: a payout to a PENDING wallet is refused with 400 Bad Request;
  • a payout to a wallet not in Brazil needs an outputPurposeCode on its quote.

Wallets you registered before keep their status: list the ones still PENDING with GET /v2/account/beneficiaries/wallets/?qualificationStatus=PENDING and qualify them before that date.

FieldTypeDescription
isSelfCustodyboolWhether the counterparty holds the wallet's private keys. Needed to qualify.
custodianNamestringThe institution that holds the keys, such as an exchange (e.g. Example Exchange). Needed to qualify when isSelfCustody is false; not accepted when it is true. Up to 100 characters.
counterpartyNamestringThe person or company that owns the wallet: whoever receives the payout. Needed to qualify. Up to 100 characters.
counterpartyCountrystringWhere the wallet is held. When isSelfCustody is false, the custodian's country, whoever owns the wallet (e.g. PY for an exchange in Paraguay, BR for an exchange in Brazil holding it for a foreign customer). When isSelfCustody is true, the counterparty's country: an individual's country of residence or a company's country of incorporation. ISO 3166-1 alpha-2 code from Countries. Needed to qualify.
isSameEconomicGroupboolOnly when counterpartyCountry is not BR: whether the counterparty is a company of your economic group. Needed to qualify a wallet abroad for a company account; always false for an individual account (omit it).

Which fields a complete qualification needs:

isSelfCustodycounterpartyCountryAlso needed
trueBRcounterpartyName
trueAny other countrycounterpartyName, isSameEconomicGroup (company account)
falseBRcounterpartyName, custodianName
falseAny other countrycounterpartyName, custodianName, isSameEconomicGroup (company account)

The wallet is QUALIFIED only when its qualification is complete and valid. Through November 14, 2026, a missing field does not fail the request: the wallet is PENDING and keeps the valid fields you sent. From November 15, 2026, an incomplete qualification is refused with 400 Bad Request naming the first missing field. Nothing is assumed: no field gets a default value, the country included. A field sent with an invalid value returns 400 Bad Request naming it, and nothing is stored. See the rules.

Qualification status​

Every wallet returns a qualificationStatus and an acamGroup:

qualificationStatusMeaning
QUALIFIEDThe qualification is complete and valid.
PENDINGNo qualification, or an incomplete one. Complete it with Qualify a Beneficiary Wallet.

acamGroup is I for a wallet qualified abroad, III for a self-custody wallet qualified in Brazil, and null otherwise (a PENDING wallet included).

Create Beneficiary Wallet​

Registering a new beneficiary wallet is straightforward. Let’s look at the 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, ETHEREUM, BASE, TRON). A wallet can only receive the tokens supported on its network: see Supported Networks and Tokens.
walletMemostringNoMemo for the wallet.

The body also takes the wallet's qualification: isSelfCustody, custodianName, counterpartyName, counterpartyCountry and isSameEconomicGroup. It is optional through November 14, 2026 and required from November 15, 2026.

The response returns only the wallet id; read its qualificationStatus with Get Beneficiary Wallet by ID. The purpose code is not part of a wallet: state it on each quote.

info

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

info

On an account that requires multi-signature approval, creating a wallet (CREATE_BENEFICIARY_WALLET) returns 202 Accepted with {"operationId": "...", "status": "PENDING"}: the wallet is created only once the operation is approved.

Endpoint​

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

Request body​

JSON
{
"alias": "ExampleAlias",
"description": "Example description",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"walletChain": "POLYGON",
"walletMemo": "memooo",
"isSelfCustody": true,
"counterpartyName": "John Doe",
"counterpartyCountry": "BR"
}

Request example​

cURL
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": true,
"counterpartyName": "John Doe",
"counterpartyCountry": "BR"
}'

Response​

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

Get all Beneficiary Wallets​

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

Endpoint​

GEThttps://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.
qualificationStatusstringQUALIFIED or PENDING. PENDING lists the wallets to qualify.
createdAfterint64Unix epoch timestamp in milliseconds (UTC) — e.g. 1700000000000. Returns results created on or after this instant (createdAt >= createdAfter).
createdBeforeint64Unix epoch timestamp in milliseconds (UTC) — e.g. 1800000000000. Returns results created strictly before this instant (createdAt < 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.

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.

Request example​

cURL
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"

Response​

JSON
{
"wallets": [
{
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"alias": "ExampleAlias",
"description": "Example description",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"walletChain": "POLYGON",
"walletMemo": "memo",
"isSelfCustody": true,
"custodianName": "",
"counterpartyName": "John Doe",
"counterpartyCountry": "BR",
"isSameEconomicGroup": null,
"qualificationStatus": "QUALIFIED",
"acamGroup": "III",
"createdAt": "2025-02-20T14:13:02.065846Z"
}
],
"cursor": "MjAtMTc0MDA2MDc4MjA2NQ..."
}

Get Beneficiary Wallet by ID​

Retrieve the details of a specific beneficiary wallet:

Endpoint​

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

Request example​

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

Response​

JSON
{
"wallet": {
"id": "00000000-0000-0000-0000-000000000000",
"userId": "00000000-0000-0000-0000-000000000000",
"alias": "ExampleAlias",
"description": "Example description",
"walletAddress": "0xXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
"walletChain": "POLYGON",
"walletMemo": "memo",
"isSelfCustody": true,
"custodianName": "",
"counterpartyName": "John Doe",
"counterpartyCountry": "BR",
"isSameEconomicGroup": null,
"qualificationStatus": "QUALIFIED",
"acamGroup": "III",
"createdAt": "2025-02-20T14:13:02.065846Z"
}
}

Qualify a Beneficiary Wallet​

Declares, completes or corrects the qualification of a wallet. It takes the same fields and rules. The qualification is replaced whole by what you send, so send the full qualification every time: a field you leave out is cleared. The wallet is QUALIFIED when it is complete. An incomplete one leaves it PENDING through November 14, 2026, and is refused from November 15, 2026. Only the qualification fields are accepted: any other field, such as alias, walletAddress, walletChain, walletMemo or purposeCode, returns 400 Bad Request ("only the qualification fields are accepted").

Endpoint​

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

Request example​

cURL
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": false,
"custodianName": "Example Exchange Ltd",
"counterpartyName": "Example Holdings LLC",
"counterpartyCountry": "US",
"isSameEconomicGroup": false
}'

The response is 200 OK with the updated wallet, as {"wallet": {...}}.

info

To qualify a sub-account's wallet, pass the subAccountId field as a query parameter. It requires the Beneficiary or Admin permission; otherwise it returns 403 Forbidden.

info

On an account that requires multi-signature approval, the request returns 202 Accepted with {"operationId": "...", "status": "PENDING"}: the qualification is applied automatically, on behalf of the requester, once the approvals of the operation (QUALIFY_BENEFICIARY_WALLET) reach the quorum. See Automatic execution.

Countries​

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

Endpoint​

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

Response​

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

Delete Beneficiary Wallet​

Delete a specific beneficiary wallet:

Endpoint​

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

Request example​

cURL
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.